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STROLLING THROUGH valFORTH 1.1 




Welcome. For this excursion you'll need an ATARI 800 (or 400) with at least 
24K, a disk drive, monitor, a printer, and valFORTH 1.1. You could even do 
the Pinter. Please get everything up and running, and boot 

Vd IrURTH. 


(To boot the disk, turn the drive(s) on and the computer off. Insert the disk 
in drive 1 and turn the computer on. The disk should now be booting, and the 
monitor speaker should be going beep-beep-beep-beep as valFORTH loads.) 

ERRORS, RECOVERIES, CRASHES 


Beiore we get started, set's mention the inevitable: Most of the time when 
you make an error you'll receive one of the fairly lucid fig-Forth error 
messages. you just get a number, this will probably refer to the Atari 
ewot message list which you can find in the documentation that came with your 
computer. Since the Atari is a rather complex beast, you may sometimes get 
isi lO a tangie that looks worse than it is. Keep your head. If you have party- 
color trash on the screen, for instance, and yet you can still hear the 
"peek-peek-peek” of the key when you hit return, you may have merely blown 
the display list without hurting your system. Try Shift-Clear followed by 
0 GR. . Very often you're home again. If this doesn’t work, try a warm start: 
Hold down a CONSOLE button, say START, and while you've got it down, press 
SYSTEM RESET and hold both for a moment until the "valFORTH" title comes up 
(If you were to push the SYSTEM RESET button alone, you'd get a cold start', 
which takes you back to just the protected dictionary.) A warm start gets 
y° u back so the 'ok 1 prompt without forgetting your dictionary additions. 

If warm start doesn't work, your system is being kept alive only by those 
wire,, connected to it, it no monger has a ‘ife of its own. The standard 
procedure now is to push SYSTEM RESET alone a few times (cold start) in a 
superstitious manner, and then reboot the system. 


Look carefully at the code that blew the system last time. If you're really 
haying trouble debugging, sprinkle a bunch of WAIT's and/or .S's (Stack 
Printouts) through the code, and go through again. The best thing about those 
nrst few long debugging sessions in any computer language is that they teach 
you the value of writing code carefully. 
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FORMATTING AND COPYING DISKS 


You may have noticed that your system came up in a green screen. In a little 
while you'll be able to change it to anything you like. We'll get to that in 
a moment, but right now type 170 LIST (and then hit RETURN.) Behold the table 
of contents. Our first priority should be to make a working disk by copying 
the original. 

Let's assume that you have a blank, unformatted disk on which to make your 
copy. Notice the line called FORMATTER on screen 170. At the right side of 
this line is probably 92 LOAD, though the number may be different in later 
releases. Type 92 LOAD (or whatever the number is) and wait until the machine 
comes back with "ok". Now you’re going to type FORMAT, but for safety’s 
sake why not remove the valFORTH disk and insert the blank disk? One never 
knows if newly purchased software will give you warnings before taking action. 
("Warnings" or "Prompts" make a system more friendly.) Ok, now type FORMAT. 

For the drive number you probably want to hit "1", unless you've got more 
than one drive and don't want to’ format on the lowest. In answer to the next 
prompt, hit RETURN unless you've changed your mind. Now wait while the machine 
does the job. If you get back "Format OK" you're in business. (If "Format 
Error" comes back, suspect a bad blank disk or drive.) You might as well 
format another disk at this time on which to store your programs. 

Now to make the copy. Return the valFORTH disk to the drive and do 170 LIST 
again. Find DISK COPIERS and do 72 LOAD, or whatever number is indicated. 

When the "ok" prompt comes back, two different disk copying routines are 
loaded: DISKC0PY1 for single drive systems and DISKC0PY2 for multiple 
drive systems. Type whichever of these words is appropriate and follow the 
instructions, ("source" means the disk you want to copy, "dest." is the 

blank "destination" disk.) There are 720 sectors that have to be copied. 

Since this can’t be done in one pass, if you are using DISKC0PY1 you will 
have to swap the disks back and forth until you're done. (The computer will 
tell you when.) The less memory you have, the more passes; there is great 
benefit in having 48K. If you have more than one drive, it still takes 
several internal passes, but there is no swapping required. Either way, the 
process takes several minutes with standard Atari disk drives. 































Nice going. Now store the original disk in some safe place. Don't write 
protect your copy yet. First we'll adjust the screen color to your taste. 

Just to see if you really have a good copy, hoot it. This can be done by 
the usual on-off method, or by typing BOOT. 

COLORS 

Before playing with the colors, let's look at something else. Type VLIST, 
and watch the words go by. These are all of the commands that are currently 
in the "dictionary” in memory in your system. You can cause this listing, or 
any other, to pause by hitting CTRL and 1 at the same time. This is a handy 
feature of the Atari. The listing is restarted with the next CTRL 1. 
Additionally, in valrORTH most listings may be aborted by pressing any of the 
three yeilow buttons START, SELECT, and OPTION. These three buttons together 
will be referred to as the CONSOLE. 

Do VLIST again, and abort it with a CONSOLE press after a few lines. At the 
top of the list you should see the word TASK. Remember that for a moment. 

Do 170 LIST again. Look over the list and find COLOR COMMANDS, and LOAD as 
appropriate. Now do VLIST again, and stop the list when it takes up about 
haif or the screen. Above TASK you now can see a number of new commands, or 
"words" as they are commonly called in Forth. These were added to the 
dictionary by the LOAD command. Here's what some of these words do: 

Type BLUE 12 B00TC0L0R, and you get a new display color. Try BLUE 2 B00TC0L0R. 
If you try this action with the number as 4, the letters will disappear, and 
you'll have to type carefully to get them back. The number is the luminance 
or "lum" and is an even number in the range 0 to 14. The color-name is called 
the "hue." The word "color" will be used to refer to a particular combination 
of hue and lum; hence PINK 6 is a color, PINK is a hue. There are 16 hues 
available and you can read their names from the display, starting with LTORNG 
( light orange) and ending with GREY. (The hues may not match their names on 
your monitor. Later on you'll be able to change the names to your liking, or 
eliminate them altogether to save memory, and just use numbers. For instance, 
PINK is equal to 4.) 

Try out different colors using BOOTCOLOR, until you find one you can live with 
tor a while. We usually use GREEN 10 or GREEN 12 in-house at Valpar. While 
you are doing this you'll probably make at least one mistake, and the machine 
will reply with an error message like "stack empty." Just hit return to get 
the "ok" back and start whatever you were doing again. Actually, you don't 
even have to get the "ok" back, but it's reassuring to see it there. When 
you've got a color you like, do VLIST again. Note the first word above TASK. 

It should be GREY. Carefully type FORGET GREY, and do VLIST again. Notice 
that GREY and all words above it are indeed forgotten. That's just what we 
want. Now type SAVE. You'll get a (Y/N) prompt back to give you a chance to 
change your mind, since SAVE involves a significant amount of writing to 
drive #1. For practice, check to see that you Still have the copy in drive 
one, and if it is there, hit Y, and off we go. When "ok" comes back, remove 
the disk and apply a write protect tab to it. Boot this disk again to see 
that it will come up in your selected color. 



DEBUGGING 


Look at 170 again. Load the DEBUGGING AIDS, and type ON STACK. You'll see that 
the stack is empty. Great, what's a stack? The best answer to this is to 
suggest that you read Leo Brodie's book. Starting FORTH . This amusing and 
thorough treatment of FORTH starts from the novice level and continues on to 
most of the advanced concepts in FORTH. Starting F ORTH is available from many 
sources, including Valpar International. Included with your valFORTH package 
is a document called "Notes on Starting FORTH for the fig-FORTH User" which 
pinpoints differences between Brodie's dialect of FORTH, called 79 Standard, 
and the somewhat more common fig-FORTH on which valFORTH was.based. 

It is not feasible to present a course on FORTH in these pages, since FORTH 
is far more powerful than BASIC, which itself requires a fair amount of space 
to present. However, we'll try to be as considerate as possible to the FORTH- 
innocent. 

The visible stack is a very good debugging and practice tool. Tyne 
a few integers, say 5 324 -19 0 and hit RETURN. The numbers are now 
visible on the stack. Top of stack, TOS, is at right. Print the top entry 
by typing " . " and then do DUP. Note that there are now two -19's on top. 

Do " * " to multiply them together. Now do DROP to discard the product, 361, 
currently at TOS. Ok, now do SWAP to exchange the 324 and 5 and then do " / " 
to divide 324 by 5. This should leave 64, since the answer is truncated. Now 
type 1000 * and notice that instead of getting 64000 you get -1536. This 
is of course two's complement on a two-byte number. Type U.S which will 
switch the visible stack to unsigned representation. Type .S to go back. 

The words .S and U.S may be used with the visible stack on or off to show 
the stack one time. Now type OFF STACK. Type in a few more numbers, say 
1234567. ON STACK again, and observe that the entries are retained. 

Do OVER to bring a copy of the 6 over the 7. Now DROP it. Do ROT to rotate 
the third from top, 5, to the top. Now do <R0T to put it back. In addition 
to all of these normal routines, valFORTH supports PICK and ROLL both coded 
in 6502 for speed. Notice that the 5th on stack is a 3. 5 PICK will bring a 
copy of it to TOS. Do this and then DROP the 3. Do 5 ROLL to pull the 3 
out of the stack and place it at TOS. DO SP! to clear the stack. 






































One point about number bases: Riaht now you're in DECIMAL. By typinq 
HEX you go into hexadecimal, and typing DECIMAL or its abbreviation DCX 
you get back. And, as usual, virtually any base may be used by typina N BASE ! 
where N is the base you want. Thus, 2 BASE ! gives binary, etc. Some errors, 
particularly during loading, may leave you in an unexpected base, like base 0^ 
for instance. If you find the machine acting normally except for numbers, this 
may have happened. A simple DCX will get you back to decimal. The word B? 
will print the current base in decimal. Put 30 on the stack and then do HEX. 

Now do B?. Do DCX to return to decimal. 

While we're on the subject of numbers, do ON and note that it is just a CONSTANT 
equal to 1. Similarly, do OFF and see that it is zero. Try 0 STACK and then 
1 STACK. The words ON and OFF are provided to enhance readability of code, 
but could be substituted by 1 and 0 if desired. The two representations are 
equally fast. 

We mention to the newcomer to FORTH that the stack takes the place of dummy 
variables or dummy parameters in other languages. This reduces memory overhead 
in several ways but does exact a penalty of reduced readability of FORTH source 
code. Consistent and sensible source code formatting can significantly enhance 
readability. The source code on the present disk may be used as a reasonably 
good example of well-arranged code. 



Now a few words about DECOMP. Clear the stack. Type in 3 and 4. Do 
OVER OVER followed by 2DUP and notice that these two phrases have the same 
effect. Clear the stack and then turn it off if you like, and do DECOMP 2DUP. 
What you see is a decompilation of 2DUP which indicates that it is indeed 
defined as OVER OVER. Decomp OVER. The word "primitive" in the decompilation 
of OVER indicates that OVER is defined in machine code. 

Decomp LITERAL. The word (IMMEDIATE) after LITERAL in the decompilation 
indicates that LITERAL is iimsediate. Not all words can be decompiled by 
DECOMP, and sometimes trash will be printed with long pauses between lines. 

In this case, hold down any CONSOLE button (the three yellow ones, remember) 
until the "ok" comes back. This may take several seconds, but rarely much 
longer. 









PRINTING 


If you have a printer attached, we can generate some hardcopy. Look at screen 
170 again. You can see the line labeled PRINTER UTILITIES.' Don't load it, 
though, she printer utilities were loaded automatically when you loaded the 
debugging aids, and so are in the dictionary already. (There is no need to 
have them in twice, though it wouldn't hurt.) You have access to the words P:, 
S:, LISTS, PLISTS, PLIST, and a couple of others relating to output. Do VLIST 
and see if you can spot this group. As a matter of fact, do ON P: VLIST OFF 
P: ail in one shot. ON P: is used to route output to the printer or not. 

OFF P: stops sending to the printer. Try ON P: OFF S: 170 LIST CR OFF P: ON S: 
and notice that this time text is not sent to the display screen, only to the 
printer. That's because of OFF S: . 

Look at screen 170 again, either on display or in hardcopy, and note which 
screen the printer utilities start. Type this number in, but don’t type load. 
Instead, after the number, type 10 PLISTS. This prints 10 screens starting 
from the first screen you just typed in. If you have a reasonably smart 
printer, it will automatically paginate, so that the screens are printed 
three to a page. If the printer acts peculiarly after printing each third 
screen, the pagination code in the word EJECT is probably not right for your 
printer. You'll be able to change this later on. 

Now type 30 150 LISTS and after a few blank screens you'll see the entire disk 
go by, except for the boot code. You can pause any time by CTRL 1 or stop 
by holding a CONSOLE button. 

Finally, do ON P: 30 179 INDEX OFF P: to print a disk index. The index is 
made up of the first line of each screen. 



EDITING 


Two editors have been included in this package. The fig (Forth Interest Group) 
Editor and the valFORTH 1.0 Editor. The latter, while a perfectly useable 
video-display editor in its own right, is actually a stripped-down version of 
the valFORTH 1.1 Editor, available with the Utilities/Editor package from Valpar 
International. The 1.0 Editor is provided to give the user some idea of what 
the very powerful 1.1 Editor is like, without actually providing it. (Among 
other things, the 1..1 Editor has a user-definable line buffer of up to 320 lines 
with a 5 line visible window at the bottom of the display. This window can be 
seen at the bottom of the 1 0 Editor, but is inactive.) 
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The fig Editor is a general-purpose FORTH line editor, and was the FORTH editing 
workhorse until good video-displays were developed. 

The fig Editor User Manual is located just after this section. It is based 
on that by Bill Stoddart of FIG, United Kingdom, published in the fig-Forth 
installation mar f the FORTH 

INTlRESi GROUP, P.0. Box 1.105, San Carlos, CA 94070. Serious Forth programmers 
should write FIG to request their catalog sheet of references and publications. 

Let's look at the valFORTH editor 1.0. Refer to the directory again, screen 170, 
and load the valFORTH editor. (Don't load the fig Editor by mistake.) Before 
proceeding, make sure that the write-protect tab on your disk is secure. The 
word to enter the editor at the screen on top of stack is V. You can remember 
it by thinking of it as "view." Type 170 V. Screen 170 is now on the display 
again, but in the valFORTH 1.0 Editor rather than as a listing. This Editor 
1S a subset of the valFORTH 1.1 Editor available in the Editor/Utilities package, 
which is MUCH more powerful and convenient, and is priced far lower than any 
comparable product of which we are aware. The Editor Command card provided 
shows all of the commands available with the 1.1 Editor. Commands available 
with the 1.0 Editor are marked with asterisks (*) on the card. Let's run 
through them: 

The cursor can be moved as in the Atari "MEMO PAD" mode. That is, hold down 
the control key (CTRL) and move the cursor around the display with the four 
arrow keys. To enter text (replace mode only in 1.0), position the cursor and 
type it in. Delete characters with the backspace key as usual. The cursor 
will wrap to the next line at the end of a line, and to the top of the screen 
when it goes off the bottom. You can type at will on this screen since we 
won't save the changes to disk. 

Do a Shift-Insert and notice that a blank line is inserted at the cursor line. 

The bottom line is lost, though it is recoverable in the 1.1 version. Now do 
Shift Delete to remove a line. (Delete is on the Backspace key). These are 
all of the Editing commands available in the 1.0 Editor. There are two methods 
of exiting the editor, CTRL S and CTRL Q. CTRL S marks the screen for saving 
to disk, and CTRL Q forgets the latest set of editing changes. As usual, 
changes are not saved immediately. This is accomplished with the word FLUSH 
or by bringing other screens into the buffers and pushing the edited ones out. 
Again, as usual, the EMPTY-BUFFERS command, or its valFORTH abbreviation, MTB, 
will clear all buffers, thus forgetting any changes that have not yet been 
written to disk. 

Try CTRL Q to exit now. Reedit the screen by typing L. L does not require an 
argument on stack and will bring the last-editing screen into the editor. The 
words CLEAR and COPY have their normal meanings, as does WHERE, which has had 

See the glossary for details. Note that since 
COPY in valFORTH does not FLUSH its changes, careful use allows transfers 
of single screens between disks by swapping disks after COPY and before 
FLUSH. This is particularly handy, for example, for transferring error 
message screens 176-179 between disks. 




You can make this transfer by doing 


176 176 COPY 177 177 COPY 178 178 COPY 179 179 COPY 

and then swapping in the destination disk and typing FLUSH. You may want 
to define a word to do this automatically: 

: ERRXFR ( — ) 

CR Insert source and press START" WAIT 

180 176 
DO I I COPY 
LOOP 

CR Insert dest. and press START" WAIT 


Because there are four 512 character screen buffers in memory in valFORTH, 
four 512 characters screens at a time is the maximum for this method. 

Bulk screen moves on a single disk or between disks are available with 
the Utilities/Editor Package. 


Note: The word "screen" in Forth refers to an area of the disk. When you 

do 170 LIST you are listing screen 170. In valFORTH there are 180 screens, 

numbered 0-179, on the disk in drive 1. In multiple-drive systems screen 

numbers continue across drives, so that screens 180-349 are on drive 2. 

180 LIST will automatically read from drive 2. For technical reasons screen 0 
should not be used for program code. 

Whichever editor you use for the moment, you can write your programs to a 
blank disk and load them from there. Remember that in fig-FORTH (and so 
also in valFORTH), if you wish to continue loading from one screen to the 
next, all but the last screen should end in —>. You'll see this all through 
the valFORTH 1.1 code. You’ll also see ==>. For present purposes you can 
use —> everywhere, and forget about ==>. ==> is actually a "smart" version 

of --> that does nothing if the system uses 1024 character screens instead of 
512. 

If you are a F0RTHER, and wish to use 1024 byte screens, do FULLK. To return 
to 512 character screens, do HALFK. (A working disk may be SAVE'd in either 
condition.) Note that the valFORTH 1.0 Editor will not edit 1024 character 
screens, though the 1.1 version will, and includes special IK notation. In 
the same vein, the word KL0AD that appears in the source code is a smart load. 
See the Glossary for details. 

To terminate loading one simply omits the --> on the last screen. ;S may be 
used to end loading at any point. Also note that valFORTH —> and ==> are 
smart in the sense that if you wish to stop loading before the machine is 
ready to stop, simply hold down a CONSOLE button. When --> or ==> execute, 
they first check the CONSOLE. If a button is pressed, they stop loading 
instead of continuing with the next screen. 




Before leaving editing practice, type MTB to empty the disk buffers and assure 
yourself that nothing will be flushed to disk accidentally as you read in new 
screens. Or else, do FLUSH if you really want to save your changes. 

(Remember to remove the write-protect tab if you do.) 


GRAPHICS 

On to Graphics. Check screen 170 and load the Color Commands again, and then 
the Graphics Package. VLIST to see what you’ve got, and print the list if 
you like. You may notice that GR. is not among these freshly loaded words: 

It is in the kernel, that is, the booted code. Try the following sequence: 

G" TEST' 1 (Send text to graphics area) 

G" TEST" (More text) 

: SMPL 4 0 DO I COLOR G" TEST" LOOP ; (automate) 

SMPL SMPL SMPL (Try it out) 

: MANY BEGIN SMPL 7TERMINAL UNTIL ; (More automation) 

2 GR. 2 PINK 8 SE. MANY (Use SE. to change color 2) 

area of the Graphics routine screens you loaded recently. When you find the 
Graphics examples screen, load it. Then do FBOX. Take a look at the code 
and then at the Glossary to get the idea. 

As in Atari Basic, adding 16 to the graphics mode you want to enter gives 
non-split screen, and adding 32 suppresses erase-on-setup of the mode. 













SOUNDS 

As a final stop on this tour, load the SOUNDS words. The word SOUND acts 
similarly to the Basic command SOUND. In valFORTH it also has the abbrevia¬ 
tion SO. and expects stack arguments like so: 

channel(0-3) frequency#(Q-255) distortion(0-14 evens) volume (0-15). 

(We use "CatFish Don't Vote" as a mnemonic). 

Try, for instance 0 200 12 8 SO. and then turn it off with 0 XSND which 
just shuts off the indicated voice, 0, or XSND4 which quiets everything. 

More about sound generation by the Atari may be found in the "sound" section. 

Logical Line Input 

One of the nice features of the Atari OS is that it lets you back the cursor 
over code that you’ve typed in already, even edit it with various inserts, 
deletes, and retypes, and then hit return to have it reinterpreted. This 
function is supported by valFORTH, and you can re-input up to two full lines 
of text, (and a wee bit more) at a time just by moving the cursor onto the 
logical line" you wish to re-read. Try it. 

THE GREAT SCREEN SIZE DEBATE 

ihe "standard" Forth screen is composed of 1024 bytes. This is a nice round 
number, and on a good text display one can have room for that many characters 
plus a few more. However, beyond tradition, there is very little functional 
reason to have 1024 byte screens over several other power-of-2 sizes. In the 
case of Atari and Apple machines, 512 byte screens make video display editors 
much easier to work with, since one can get a whole screen in the display 
at once. valFORTH supports both 1024 and 512 byte screen modes, but in-house 
at V'alpar we strongly prefer 512 byte screens and recommend that you adopt 
this as your personal standard. If at any time you wish to change to IK to 
help compile software written on IK screens, you can do so with one word, 
FULLK. 
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SAVING YOUR FAVORITE SYSTEM(S) 


Well, you've seen many of the bells and whistles of valFORTH. When you are 
using the language for software development you will probably have a favorite 
set of capabilities that you always want aboard. Rather than loading them 
from scratch each time, why not SAVE them to a formatted disk? Just get 
everything you want into the dictionary. After it’s all loaded, put a 
formatted disk into drive 1 and type SAVE. Answer the prompt by pressing "Y" 
unless you have changed your mind, and the computer will save a bootable copy 
of your system dictionary on the blank disk. 

DISTRIBUTING YOUR PROGRAMS 

If you have a program you wish to distribute, there are two ways in which to 
proceed: 

(1) Make a PROTECTED auto-booting copy of your software by using the 

word AUTO as detailed in the "compiling Auto-Booting Software" section 
of this manual. 

(2) Make a TARGET-COMPILED version of your software, using the valFORTH 
Target Compiler, scheduled for release approximately 9/82. Target 
Compilers allow production of much smaller final FORTH products'by 

buffers, etc. 

requires that the message: 

Forth Interest Group, P.0. Box 1105, San Carlos, CA "94070 


Hope you've enjoyed the tour. Bye now. 














THE FORTH INTEREST GROUP LINE EDITOR 




of FIG, United Kingdom 


FIG EDITOR USER MANUAL 


Based on the Manual 
by Bill Stoddart 


valFORTH organizes its mass storage into "screens" of 512 characters, with the 
option of 1024. it, tor example, a diskette of 90K byte capacity is used 
entirely for storing text, it will appear to the user as 180 screens numbered 
0 to 179. Screen 0 should not be used for program code. Each screen is 
organized as 16 lines with 32 characters per line. 


Selecting a Screen and Input of Text 


io start an editing session the user types EDITOR to invoke the appropriate 
vocabulary. 

The screen to be edited is then selected, using either: 
n LIST (list screen n and select it for editing ) OR 

To input new text to screen n after LIST or CLEAR the P (put) command is used. 



Example: 


0 P THIS IS HOW 

1 P TO INPUT TEXT 

2 P TO LINES 0, 1, AND 2 OF THE SELECTED SCREEN. 


Based on material provided through the courtesy of the FORTH INTEREST GROUP, 
P.0. Box 1105, San Carlos, CA 94070. 
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Line Editing 

During this description of the editor, reference is made to PAD. This is a 
text buffer which may hold a line of text used by or saved with a line editing 
command, or a text string to be found or deleted by a string editing command. 





PAD can be used to transfer a line from one screen to another, as well as to 
perform edit operations within a single screen. 


Line Editor Commands 


n H Hold line n at PAD (used by system more often than by user). 

N D Delete line n but hold it in PAD. Line 15 becomes blank as lines 

n+1 to 15 move up 1 line. 

n T Type line n and save it fn PAD. 

n R Replace line n with the text in PAD. 


n I 


n E 
n S 


Insert the text from PAD at line n, moving the old line n 
and following lines down. Line 15 is lost. 

Erase line n with blanks. 

Spread at line n. n and subsequent lines move down 1 line. 
Line n becomes blank. Line 15 is lost. 
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Cursor Control and String Editing 

The screen of text being edited resides in a buffer area of storage. The 
editing cursor is a variable holding an offset into this buffer area. Commands 
are provided for the user to position the cursor, either directly or by search¬ 
ing for a string of buffer text, and to insert or delete text at the cursor 
position. 

Commands to Position the Cursor 

TOP Position the cursor at the start of the screen. 

N M Move the cursor by a signed amount n and print the cursor line. 

The position of the cursor on its line is shown by a • (solid circle). 


F text 

String Editing Commands 

Search forward from the current cursor position until string 
"text" is found. The cursor is left at the end of the text 
string, and the cursor line is printed. If the string is not 
found an error message is given and the cursor is repositioned 
at the top of screen. 

B 

Used after F to back up the cursor by the length of the most 
recent text. 

N 

Find the next occurrence of the string found by an F command. 

X text 

Find and delete the string "text." 

C text 

Copy in text to the cursor line at the cursor position. 

TILL text 

Delete on the cursor line from the cursor till the end of the 
text string "text." 

NOTE: 

Typing C with no text will copy a null (represented by a heart) 
into the text at the cursor position. This will abruptly stop 
later compiling! T6 delete this error type TOP X 'return'. 

n LIST 

Screen Editing Commands 

List screen n and select it for editing 

n CLEAR 

Clear screen n with blanks and select it for editing 

nl n2 COPY 

Copy screen nl to screen n2. 

L 

List the current screen. The cursor line is relisted after 
the screen listing, to show the cursor position. 

FLUSH 

Used at the end of an editing session to ensure that all entries 
and updates of text have been transferred to disc. 
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Editor Glossary 


TEXT c — 

Accept following text to pad. c is text delimiter. 

LINE n — addr 

Leave address of line n of current screen. This address will be in the 
disc buffer area. 

WHERE nl n2 — 

n2 is the block no., nl is offset into block. If an error is found in 
the source when loading from disc, the recovery routine ERROR leaves 
these values on the stack to help the user locate the error. WHERE 
uses these to print the screen and line nos. and a picture of where 
the error occurred. 

R# — addr 

A user variable which contains the offset of the editing cursor from 
the start of the screen. 

ROCATE --- nl n2 

From the cursor position determine the line-no n2 and the offset into 
the 1ine nl. 

READ — line-address offset-to-cursor 

RAG — cursor-address count-after-cursor-till-EOL 

-MOVE addr line-no — 

'Move a line of text from addr to line of current screen. 

H n — 

Hold numbered line at PAD. 

E n — 

Erase line n with blanks. 

S n — 

Spread. Lines n and following move down, n becomes blank. 

D n — 

Delete line n, but hold in pad. 

M n — 

Move cursor by a signed amount and print its line. 

T n — 

Type line n and save in PAD. 

L 

List the current screen. 
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R 


n — 

Replace line n with the text in PAD. 
n — 

Put the following text on line n. 

I n — 

Spread at line n and insert text from PAD. 

TOP 

Position editing cursor at top of screen. 

CLEAR n — 

Clear screen n, can be used to select screen n for editing. 

FLUSH 

Write all updated buffers to disc. 

COPY nl n2 — 

Copy screen nl to screen n2. 

-TEXT Addr 1 count Addr 2 — boolean 
True if strings exactly match. 

MATCH cursor-addr bytes-left-till-EOL str-addr str~count 

— tf cursor-advance-till-end-of-matching-text 

ff-bytes-left-till-EOL 

Match the string at str-addr with all strings on the cursor line 
forward from the cursor. The arguments left allow the cursor R# to 
be updated either to the end of the matching text or to the start of the 
next line. 

1LINE — f 

Scan the cursor line for a match to PAD text. Return flag and update 
the cursor R# to the end of matching text, or to the start of the 
next line if no match is found. 

FIND 

Search for a match to the string at PAD, from the cursor position 
till the end of screen. Sf no match found issue an error message 
and reposition the cursor at the top of screen. 

DELETE n — 

Delete n characters prior to the cursor. 


N 

Find next occurrence of PAD text. 

F 

Input following text to PAD and search for match from .cursor position 
till end of screen. 
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B 

Backup cursor by text in PAD. 

X 

Delete next occurrence of following text. 

TILL 

Delete on cursor line from cursor to end of the following text. 

C 

Spread at cursor and copy the following text into the cursor line. 



CREATING DISKS FOR PRODUCTION 


RELOCATING BUFFERS 

;he purpose ot this section is to show you how to avoid incorporating buffer 
Space into an auto-booting program, thereby saving more than 2K in memory 
requirement for the machine on which the program will eventually run. 

Fig-FORTH (and so valFORTH) uses a virtual memory arrangement which allows 
disK areas to be accessed in a manner similar to that used to access semiconductor 
memory. We won't go into detail here; those wishing to find out more about this 
can contact FIG for documentation at: 

FORTH INTEREST GROUP 
P.0. Box 1105 
San Carlos, CA 94070 

or they can puzzle out the process by starting at the word BLOCK. For our present 
purposes, however, we simply note that the virtual memory scheme reauires that 
some continuous area of memory be allotted as buffer space for disk operation, 
valFORTH as delivered has buffer space for four 512 byte "screens" at a time 
Each screen is composed of four blocks of 132 bytes each: 128 bytes of actual 
data, corresponding to a sector, and four bytes of identification and delimiting 
data. This produces a total of 4 x 4 x 132 = 2112 bytes that are needed for 
programming and compilation* but are generally not required when software is 
actually run. In order to get the full use of your computer, particularly for 
the purposes of producing auto-booting software like games, you'll need to know 
how memory is mapped and what changes you can make in the mapping. During the 
following discussion refer to the memory map provided with your documentation. 

You will note from the memory map that the buffers are placed just above the 
kernes (boot-up) valFORTH dictionary. The dictionary pointer is set just past 
the buffers, so new word definitions will be compiled in above the end of the 
buffers. Why such an odd location? Read on... 

* Those used to seeing the buffers at the top of memory will quickly realize 
that this is impractical on the Atari, since that area^ is used for display 

s As though it is possible to an extent to fool the operating system into 
thinking that it has less memory than it actually has, and thus "reserve" an 
area at the top of memory, this is a troublesome proposition. 

* Another approach is to put the buffers just below the kernel dictionary, 
which has been done in at least one FORTH-for-Atari release. While this"is 
safe, it sacrifices 2K bytes during run time unless rather clever programming 
techniques are used on each program to put code into the dormant buffer area. 

* Clearly, the buffers should be put somewhere above the dictionary but below 
the display-list area, and a simple means to relocate them should be supported. 

This is precisely what you have in valFORTH. 


xn a pinch, you can compi 1 e using only 264 bytes of buffer memory. 
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When you have a program that will compile and run, preferably without errors, 
and you d like to create a smaller auto-boot'ing version, follow this procedure: 

* Boot the valFORTH disk. 


* 5 ecide 0n the area t0 which t0 re1ocate the buffers: If the program can be 
loaded without leaving the 0 Graphics mode or doing anything else to high memory 
while loaning, then the resjjlt printed by the sequence 


0 GR. OCX 741 @ 2113 - U (See note below.) 

will be a safe place to put the buffers; 741 @ is the Atari OS pointer to just 
df 7 current display list. (If you will be using Transients, a capability 

of the Jtilities/Editor package, their default location is 


OCX 741 @ 4000 - 

so you would be better off to put the buffers at, say, 

DCX 741 @ 6113 - 


to avoid conflict) 


Find the buffer relocation 
on screen 170 of the valFORTH 


utility listed in the table 

on screen i/uot the valFORTH disk, and load it. This is a self-promptino 

C 1 ' irKts you t0 re1oca te the buffers and then forget the utility, 

ro.iow the directions. You’ll receive a verification messaae after the buffers 
nave been moved. 


of contents starting 
a self-prompting 


Type 


1 TASK DP ! 

to move the dictionary pointer below the old buffer area. (Advanced programmers: 
This is not a typo. The cfa of TASK points to NEXT.) 

Now load your program as usual. You should probably create an auto-booting 
program at this point, rather than doing anything else, since if you run the 
program now it may write into your relocated buffers and conceivably even attempt 
a write to your disk. So, create an auto-booting version as directed in the 
mi^~' sec fi°n above. Remember that if the program is for distribution, 
you MUST protect your software and ours by using the AUTO command. 

*****CAUTI0N***** 


The buffers start out just above the kernel dictionary, as indicated, and for 
normal programming they should be LEFT THERE: Several routines on the valFORTH 
and other disks in this product line use the area between pad and the 
^ 1s P^ a Y ^ 1s t 35 a scratch area for extensive disk transfers. 
DIjKC 0P/1 and DISKC0PY2 on the valFORTH disk are examples. 


Note: The buffers should generally be relocated to an even address because of 
an Atari OS bug. See also Note 1 at end of valFORTH 1.1 Glossary. 
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COMPILING AUTO-BOOTING SOFTWARE 

Your purchase of valFORTH and its associated packages also grants you a sinole- 
user license for the software. You may not copy valFORTH or its associated' 
Valpar International products for any purpose other than for your own use as 
back-up copies. However, a word called AUTO has been provided to allow you 
to create a copy of your software that is suitable for distribution. The word 
AUTO does several things. 


* AUTO provides extensive protection both for your software and the valFORTH 
and auxiliary programs on which it is based. Your product may still be copied 
by normal^ methods, but the programming concepts on which it is based will be 
very difficult to analyze. The valFORTH and auxiliary programs will be rendered 
useless except to run your program. Since AUTO scrambles all headers in the 
code before saving to disk or cassette, even direct examination of the code on 
the medium is not very revealing. This provides essentially all the protection 
of headerless code. 



* AUTO will create a disk that autoboots to the FORTH word of your choice. 
This usually will be the last word defined in your program. In addition, a 
disk created using AUTO will not have exit points: That is, even if your 
program terminates, or makes an error because of an undiscovered bug, it will 
not exit to valFORTH and the "ok" prompt, instead, it will automatically 
attempt to start again at the original auto-boot word, and will do so unless 
an error has disabled the system. 


* AUTO allows repetitive saving of your protected software to disk and cassette 
in one sitting, with extensive prompting. This provides a short-run production 
environment. (Remember that if you want to save to cassette, the cassette 
recorder should be attached to the system at boot time; if it is attached 
after booting, the computer may not know that the recorder is there and may 
fail when trying to AUTO to cassette). 


To run AUTO and create your bootable software: 

(1) Load valFORTH. 

(2) Relocate buffers to save 2K+, if desired (see below). 

(3) Load your program. 

(4) DISPOSE transients, if you use them. (The Transient utilities come with 
the Utilities/Editor package, and allow use of "disposable assemblers" 
and the like). 

(5) Find the Auto-Boot Utility section on the valFORTH disk by referring to 
the directory starting on screen 170, and load as indicated. 

(6) Type AUTO cccc where "cccc" is the word which you wish to execute on 
auto-booting the software. You will now be prompted through the rest 
of the procedure. On exiting from AUTO you will fall through to the 
auto-booting program that you have just protected. 
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DISTRIBUTING YOUR PROGRAMS 


If you have a program you wish to distribute, there are two ways in which to 
proceed: 

(1) Make a PROTECTED auto-booting copy of your software by using the 

word AUTO as detailed in the "Compiling Auto-Booting Software" section 
of this manual. 

(2) Make a TARGET-COMPILED version of your software, using the valFORTH 
Target Compiler, scheduled for release approximately 9/82. Target 
Compilers allow production of much smaller final FORTH products by 
allowing elimination of unnecessary code, e.g., headers, compiler, 
buffers, etc. 


In addition to the above procedures, Valpar International also 
requires that the message: 

Created in whole or part using valFORTH products of 
Valpar International, Tucson, AZ 85713, USA 
Based on fig-FORTH, provided through the courtesy of 
Forth Interest Group, P.0. Box 1105, San Carlos, CA 94070 

be included either on the outside of the media (diskette, cassette, 
or other) as distributed, or in the documentation provided with the 
product. Please note that failure to include this message with 
products that include valFORTH code may be regarded as a copyright 
violation. 




valFORTH 1.1 SYSTEM EXTENSIONS 


GRAPHICS* COLORS, AND SOUNDS 


Graphics 

The Graphics package follows the Atari BASIC graphics set as closely as 
possible, and is identical in most respects. As in BASIC, the most''complex 
parts of Graphics are DRAWTO (abbreviated "DR.") and FIL, and even these are 
not too obscure. Find the Graphics Demo by looking at the directory start¬ 
ing on screen 170, and load it. Try the word FBOX, Now look at the code" 
that produced this effect, if you like. The general explanation is as 
follows: 

Display positions are denoted by two coordinates, a horizontal and a vertical 
1 he 0,0 point is in the upper left hand corner, and the vertical coordinate 
increases as you go down the display, while the horizontal coordinate increases 
as you go to the right. This is all familiar from BASIC. 

In graphics modes, a single point at position X Y can be plotted by X Y PLOT. 

1 ns color oi the point will be that in the color register declared by the 
last COLOR command. A line, again of the color in the register declared by 
the last color command, may then be drawn to point XI Y1 by XI Y1 DR. . The 
word FIL may be used to fill in an area as described in the Atari manual, 
and as illustrated in the FBOX example. The color register for the fill is 
the one whose number is on the stack when FIL is executed. Essentially, to 
set up FIL you draw in boundaries and pick two points you wish to FIL between, 
ihe first of these points is set up either by a DR. or PLOT comnand, or by 
v ^ - command. POSi has the advantage of not reguiring that you 

put anything into the place where you are positioning yourself. The second 
point for the FIL command is then set up by using POS. . The fill is then 
performed by putting a number on stack (the color register for the fill) and 
then doing FIL. 

If you are in a text mode, a single character, c , can be sent to the display 
by ASCII c CPUT. Text strings can be sent to the display with G" cccc " and 
in addition will have the color in the register specified by the last COLOR 
command before the string is output. This is a significant enhancement to 


Graphics and Color Glossary: 


SETCOLOR nl n2 n3 - 

Color register nl (0...3 and 4 for background) is set to hue n2 (0 to 15) 
and luminance n3 (0-14, evens). 

SE. nl n2 n3 — 

Alias for SETCOLOR. 


GR. n - 

Identical to GR. in BASIC. Adding 16 will suppress split display. 
Adding 32 will suppress display preclear. In addition, this GR. will 
not disturb player/missiles. 

POS. x y - 

Same as BASIC POSITION or POS. Positions the invisible cursor if in 
a split display mode, and the text cursor if in 0 GR. . 

POSIT x y — 

Positions and updates the cursor, similar to PLOT, but without changing 
display data. 


PLOT x y — 

Same as BASIC PLOT. PLOTS point of color in register specified by last 
COLOR command, at point x y. 


DRAWTO x y - 

Same as BASIC DRAWTO. Draws line from last PLOT'ted, DRAWTO'ed or 
POSIT'ed point to x y, using color in register specified by last COLOR 
command. 


DR. x y — 

Alias for DRAWTO. 


FIL b — 

Fills area between last PLOT'ed, DRAWTO'ed or POSIT'ed point to last 
position set by POS., using the color in register b. 

G" — 

Used in the form G 1 ' ccccc", Sends text cccc to text area in non-0 
Graphics mode, starting at current cursor position, in color of 
register specified by last COLOR command prior to cccc being output. 
G" may be used within a colon definition, similar to .". 


addr count — 

Starting at addr, output count characters to text area in non-0 Graphics 
mode, starting at current cursor position, in color of register speci¬ 
fied by last COLOR command. 


LOC. x y — b 

Positions the cursor at x y and fetches the data from display at that 
position. Like BASIC LOCATE and LOC. . Note that since the word LOCATE 
has a different meaning in valFORTH (it is part of the advanced editor 
in the Utilities/Editor package), the name is not used in this package. 
(Advanced users: We could put Graphics in its own vocabulary, but this 
would add some inconvenience.) 
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(G") 

Run-time code compiled in by G". 

P0S@ - x y 

Leaves the x and y coordinates of the cursor on the stack. 

CPUT b -- 

Outputs the data b to the current cursor position. 

CGET — b 

Fetches the data b from the current cursor position. 

>SCD cl — c2 

Converts cl from ATASCII to its display screen code, c2. 

Example: ASCII A >SCD 88 {? C! 

will put an ! A into the upper left corner of the display. 

SCD> cl — c2 

Converts cl from display screen code to ATASCII c2. 

See >SCD. 

>BSCD addrl addr2 count — 

Moves count bytes from addrl to addr2, translating from ATASCII 
to display screen code on the way. 

BSCD> addrl addr2 count -- 

Moves count bytes from addrl to addr2, translating from display 
screen code to ATASCII on the way. 

COLOR b - 

Saves the value b in the variable COLDAT. 

CLRBYT — addr 

Variable that holds data from last COLOR command. 

GREY 

GOLD - 1 

ORNG 

RDORNG — 3 

PINK — 4 
LVNDR 

BLPRPL — 6 (CONSTANTS) 

PRPLBL - 7 

BLUE 

LTBLUE - 9 

TURQ - 10 
GRNBL - 11 
GREEN — 12 
YLWGRN — 13 
ORNGRN — 14 
LTORNG — 15 

B00TC0L0R hue lum — 

Sets up hue for playfield 2 (text background) and lum for playfield 1 
(letter intensity) in 0 Graphics mode. Lum of playfield 2 is set at 4. 
After using BOOlCOLOR, doing SAVE will create a system disk with the 
selected color. 
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Sounds 


The actual production of sound by the Atari machines is rather complex and 
the reader is referred to the many recent (first half 1982) articles on this 
subject in various magazines. Here we will restrict comments to the function 
of the Atari audio control register. This is an eight bit register which 
valFORTH shadows by the variable AUDCTL. The bits have the following 
functions: 

bit 7: Change 17 bit polycounter to 9 bit polycounter. 

Affects distortions 0 and 8. 

bit 6: Clock channel 0 with 1.79 Mhz instead of 64 Khz. 

bit 5: Clock channel 2 with 1.79 Mhz instead of 64 Khz. 

bit 4: Clock channel 1 with channel 0 instead of 64 Khz. 

bit 3: Clock channel 3 with channel 2 instead of 64 Khz. 

bit 2: Use channel 2 as crude high-pass on channel 0. 

bit 1: Use channel 3 as crude high-pass on channel 1. 

bit 0: Change normal 64 Khz to 15 Khz. 

The value n may be sent to the audio control register by doing n FILTER!. 

SOUND chan freq dist vol -- 

Sets up the sound channel "chan" as indicated. 

Channel: 0-3. 

Frequency: 0-255, 0 is highest pitch. 

Distortion: 0-14, evens only. 

Volume: 0-15. 

Suggested mnemonic: CatFish Don't Vote 

SO. chan freq dist vol -- 

Alias of SOUND. 

FILTER! n — 

Stores n in the audio control register and into the valFORTH shadow 
register, AUDCTL. Use AUDCTL when doing bit manipulation, then do 
FILTER!. (FILTER! does a number of housekeeping chores, so use it 
instead of a direct store into the hardware register.) 

AUDCTL — addr. 

A variable containing the last value sent to the audio control register 
by FILTER!. Used for bit manipulation since the audio control register 
is write-only. 

XSND n — 

Silences channel n. 

XSND4 

Silences all channels. 
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TEXT OUTPUT AND DISK PREPARATION GLOSSARY 


S: flag — 

If flag is true, enables handler that sends text to text screen. If 
false, disables the handler. (See PFLAG in main glossary.) ON S: etc. 

P : flag — 

If flag is true, enables handler that sends text to printer. If false, 
disables the handler. (See PFLAG in main glossary.) OFF P: etc. 


BEEP — 

Makes a raucous noise from the keyboard. Is put in this package for 
lack of a better place. 

ASCII c, -- n (executing) 
c, -- (compiling) 

Converts next character in input stream to ATASCII code. If executing, 
leaves on stack. If compiling, compiles as literal. 


EJECT 

Causes a form feed on smart printers if the printer handler has been 
enabled by ON P:. May need adjustment for dumb or nonstandard printers. 

LISTS start count -- 

From start, lists count screens. May be aborted by CONSOLE button at 
the end of a screen. 

PLIST scr — 

Lists screen scr to the printer, then restores former printer handler 
status. 

PLISTS start cnt -- 

From start, lists cnt screens to printer three to a page, then restores 
former printer handler status. May be aborted by CONSOLE button at the 
end of a screen. 

FORMAT — 

With prompts, will format a disk in drive of your choice. 

(FMT) nl — n2 

Formats disk in drive nl. Leaves 1 for good format, otherwise error number. 
Note: Because of what appears to be an OS peculiarity, this operation must 
not be the first disk access after a boot. 

DISKC0PY1 — 

With prompts, copies a source to a destination disk on single drive, 
with swapping. Smart routine uses all memory from PAD to bottom of 
Display List, producing minimum number of swaps. 

DISKC0PY2 — 

With prompts, copies disk in drive 1 to disk in drive 2 using memory 
like DISKC0PY1. 


DEBUGGING UTILITIES 


DECOMP cccc 

Does a decompilation of the word cccc if it can be found in the active 
vocabularies. 

Although DECOMP is very smart, like most FORTH decompilers it will 
become confused by certain constructs, and will begin to print trash, 
with pauses in between while it looks for more trash to print. When 
this happens, simply hold down a CONSOLE button until DECOMP exits. 
This sometimes takes as much as 10 seconds, depending on luck. 


CDUMP addr n — 

A character dump from addr for at least n characters. (Will always 
do a multiple of 16.) 

#DUMP addr n — 

A numerical dump in the current base for at least n characters. 

(Will always do a multiple of 8.) 

(FREE) — n 

Leaves number of bytes between bottom of display list and PAD. This is 
essentially the amount of free dictionary space, if additional memory 
is not being used for player/missiles, extra character sets, and so on. 


FREE — 

Does (FREE) and then prints the stack and "bytes". 

H. n — 

Prints n in HEX, leaves BASE unchanged. 

STACK flag — 

If flag is true, turns on visible stack. If flag is false, turns off 
visible stack. 

.S 

Does a signed, nondestructive stack printout, TOS at right. Also 
sets visible stack to do signed printout. 

U.S 

Does unsigned, nondestructive stack printout, TOS at right. Also 
sets visible stack to do unsigned printout. 

B? 

Prints the current base, in decimal. Leaves BASE undisturbed. 

CFALIT cccc, -- cfa (executing) 
cccc, -- (compiling) 

Gets the cfa (code field address) of cccc. If executing, leaves it on 
the stack; if compiling, compiles it as a literal. Not precisely a 
debugging tool, but finds use in DECOMP. 
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FLOATING POINT WORDS 


The floating-point package uses the Atari floating point routines in the 
operating system ROM in the same way that Atari Basic does. The routines 
are rather slow, and there are no trigonometric functions internal to the 
Atari. (SIN, COS, TAN, ATN, and ATN2 have been programmed and are available 
in the Advanced Graphics/Floating Point Package.) LOG and EXP are included in the 
operating system ROM and are supported in the present package, in base 10 
and base e. Note that in the directory on screen 170 it is indicated that 
the ASSEMBLER must be loaded before loading the floating-point package. 

Floating point words have a six byte representation in the Atari OS, and since 
the stack has a 60 byte maximum, a maximum of 10 floating point numbers can be 
on the stack at a time. In practice, this maximum often becomes 9 since some 
fp routines use the stack as a scratch area. 

Operations involving floating-point numbers generally leave floating-point 
results. Exceptions are the words FIX, which takes a positive floating 
pointer number less than 32767.5 and leaves a rounded integer; and the 
floating-point comparison operators, F=, F<, etc., which leave flags. To 
get a floating-point number on the stack, use the word FLOATING or its alias, 

FP, followed by a number in Fortran !, E" format. For example, 

FP 12345 
FP 12345.6 
FP -12345.8 
FP +5432E-16 
and FP -8E18 

will all leave floating-point numbers on the stack. Floating-point variables 
and constants are also supported. 

It has been our experience that mistakes are common when first using this 
package. One must remember to use F* and not *, F+ and not +, and so on, 
when doing fp operations. Remember also that integers and fp numbers can't 
be mixed by operations: Either convert the fp number by FIX, or the integer 
by FLOAT, and then use the appropriate operation. 

Create new words as usual. For instance, to define a floating-point square 
root function, write 

: FSQRT { fp -- fp ) 

LOG FP 2 F/ EXP ; 

Overflow and underflow, and illegal operations such as dividing by 0, taking 
logarithms of negative numbers, or Fixing a negative number cause undefined" 
and rather unpredictable results, though they do not harm the system. 

(Additional words in the Utilities/Editor Package cause all but one of these 
operations to give correct or useable results; logarithms of negatives cannot 
be approximated with Real numbers.) 

The maximum and minimum numbers are generous, about 1E97 and IE-97, and it is 
sometimes possible to exceed these limits during computation. Atari's internal 
representation of floating point numbers is awkward. Refer to the Atari OS 
manual, available from Atari, for details if needed. 
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FLOATING-POINT GLOSSARY 


In the following, "fp" is used to indicate a floating-point number (six bytes) 
on the stack. The terms "top-of-stack," "2nd-on-stack" etc., have been used 
with the obvious meanings even though, because fp numbers are six bytes, their 
physical positions on the stack will not match the usual ones. 

FCONSTANT cccc, fp — 

cccc: —fp 

The character string is assigned the constant value fp. When cccc is executed, 
fp will be put on the stack. 

Example: FP 3.1415926 FCONSTANT PI 

FVARIABLE cccc, fp — 

cccc: addr — 

The character string cccc is assigned the initial value fp. When cccc is 
executed, the addr (two bytes) of the value of cccc will be put on the stack. 
Example: FP 0 FVARIABLE X 

FP 18.4 X F! 

FDUP fpl — fpl fpi 

Copies the fp number at top-of-stack. 

FDROP fp — 

Discards the fp number at top-of-stack. 

FOVER fp2 fpl — fp2 fpl fp2 

Copies the fp number at 2nd-on-stack to top-of-stack. 

FLOATING cccc, - fp 

Attempts to convert the following string, cccc, to a fp number. Stops on 
reaching first unconvertible character and skips the rest of the string. If 
no characters convertible, leaves unpredictable fp number on stack. 

FP cccc, —fp 

Alias for FLOATING. 

addr — fp 

Fetches the fp number whose address is at top-of-stack. 
fp addr -- 

Stores fp into addr. Remember that the operation will take six bytes in 
memory. 

fp — 

iype out the fp number at top-of-stack. Ignores the current value in BASE 
and uses base 10. 

addr — 

Fetches a fp number from addr and types it out. 



F+ fp2 fpl — fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their fp sum, fp3. 

F- fp2 fpl -- fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their difference, 
fp3=fp2~fpl. 

F* fp2 fpl -- fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their product, fp3. 
F/ fp2 fpl -- fp3 

Replaces the two top-of-stack fp items, fp2 and fpl, with their quotient, 

fp3=fp2/fpl. 

FLOAT n — fp 

Replaces number at top-of-stack with its fp equivalent. 

FIX fp (non-neg, less than 32767.5) — n 

Replaces fp number at top-of-stack, constrained as indicated, with its 

integer equivalent. 

\ 

LOG fpl - fp2 

Replaces fpl with its base e logarithm, fp2„ Not defined for fpl negative, 
fpl -- fp2 

Replaces fpl with its base 10 decimal logarithm, fp2. Not defined for fpl 
negative. 

EXP fpl -- fp2 

Replaces fpl with fp2, which equals e to the power fpl. 
fpl--fp2 

Replaces fpl with fp2, which equals 10 to the power fpl. 

FQ= fp — flag 

If fp is equal to floating-point 0, a true flag is left. Otherwise, a false 
flag is left. 

fp2 fpl — flag 

If fp2 is equal to fpl, a true flag is left. Otherwise, a false flag is left. 
F> _ fp2 fpl - flag 

If fp2 is greater than fpl, a true flag is left. Otherwise, a false flag is 
left. 

fp2 fpl -- flag 

If fp2 is less than fpl, a true flag is left. Otherwise, a false flag is left. 
FLITERAL fp -- 

If compiling, then compile the fp stack value as a fp literal. This definition 
is immediate so that it will execute during a colon definition. The intended 
use is: 

: xxx [ calculate ] FLITERAL ; 

Compilation is suspended for the compile time calculation of a value. 
Compilation is resumed and FLITERAL compiles the value on stack. 
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FLIT - fp 

Within a colon definition, FLIT is automatically compiled before each fp 
number encountered as input text. Later execution by the system of FLIT as 
it is encountered in the dictionary cause the context of the next 6 dictionary 
addresses to be pushed to the stack as a fp number. FLIT is also compiled 
in explicitly by FLITERAL. 

ASCF addr — fp 

An ASCII-to-floating-point conversion routine. Uses Atari OS routine. The 
routine reads string starting at addr and attempts to create a floating point 
number. If string is not a valid ASCII floating-point representation, leaves 
undefined result on stack. Used by FLOATING. 

FS fp - 

System routine. Sends fp argument on stack to Atari register FRO. Experts 
only. 

>F -- fp 

System routine. Fetches fp argument from Atari register FRO. Experts only. 

<F fpl fp2 -- 

System routine. Sends fpl and fp2 to Atari registers FR1 and FRO respectively. 
Experts only. 


F.TY 

System routine. Types out last fp number converted by FASC. 

CIX addr -- 

System variable. One byte offset pointer in buffer pointed to by INBUF. 
Experts only. 

INBUF addr — 

system variable. Used by ASCF to know where ASCII string to be converted is 
located. 

FR1 - n 

System constant. Atari internal register address. 


FRO —n 

System constant. Atari internal register address. 

FPOLY addr count — 

A system routine for advanced users doing polynomial evaluation. 

The polynomial P(Z) = SUM(i=0 to n) (A(i)*Z**i) is computed by the following 
standard method: 

P(Z) = (...(A(n)*Z + A(n-l))*Z + ... + A(1))*Z + A(0) 

The address addr points to the coefficients A(i.) stored sequentially in memory, 
with the highest order coefficient first. The count is the number of coeffi¬ 
cients in the list. The independent variable Z, in floating-point, should be 
sent to FRO using FS. FPOLY is then executed. The result put on the stack 
using >F. Note that FPOLY is intended to be used in a Forth word, 
irigonometric functions and general polynomial expansions, for example, may 
be defined more simply with the help of this routine. 
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FLG10 

System routine used by L0G10. 

FLG 

System routine used by LOG. 

FEX 

System routine used by EXP. 

FEX10 

System routine used by EXP10. 

FDIV 

System routine used by F/. 

FMUL 

System routine used by F*. 

FSUB 

System routine used by F-. 

FADD 

System routine used by F+. 

FPI 

System routine used by FIX. 

IFP 

System routine used by FLOAT. 

FASC 

System routine, Does floating-point-to-ASCII conversion 
in FRO and leaves string at address pointed to by INBUF. 
has most significant bit set. Used by F.TY. 

AFP 

System routine used by ASCF. 


on the fp number 
Last byte of string 


(intentionally left blank) 
















OPERATING SYSTEM 


This package implements the computer's Operating System I/O routines. The 
850 (RS-232C) driver package may be loaded into the dictionary by using the 
word RS232, which will then support references to devices "Rl" through'"R4." 

The code for this section was originally written by Patrick Mullarky, and 
published through the Atari Program Exchange. It is used here by permission 
of the author. 

OS GLOSSARY 

OPEN addr nl n2 n3 -- n4 

This word opens the device whose name is at addr. The device is opened 
on channel n3 with AUX1 and AUX2 as nl and n2 respectively. The device 
status byte is returned as n4. The name of a device may be produced in 
various ways: For a single character name, say "S" for the screen 
handler, 

ASCII S PAD C! 

will leave the ASCII value of S at PAD. Then 

PAD 803 OPEN 

will open the screen handler on channel 3 with AUX1 = 8 (write only) 
and AUX2 = 0. If you have the UTILITIES/EDITOR Package, longer names 
may be set up simply by using the word " . 

CLOSE n — 

Closes channel n. 

PUT bl n - b2 

Outputs byte bl on channel n, returns status byte b2. 

GET n -- bl b2 

Gets byte bl from channel n, returns status byte b2. 

GETREC addr nl n2 -- n3 

Inputs record from channel n2 up to length nl. Returns status byte n3. 
PUTREC addr nl n2 — n3 

Outputs nl characters starting at addr through channel n2. Returns 
status byte n3. 

STATUS n - b 

Returns status byte b from channel n. 

DEVSTAT n - bl b2 b3 

.■ ram channel nl gets device status bytes bl and b2, and normal status 

byte b3. 

SPECIAL bl b2 b3 b4 b5 b6 b7 b8 — b9 

Implements the Operating System "Special" command. AUX1 through AUX6 
are bl through b6 respectively, command byte is b7, channel number is 
b8. Returns status byte b9. 

RS232 

Loads the Atari 850 drivers into the dictionary (approx 1.8K) through 
a.three-step bootstrap process. Executing this command more than once 
without turning the 850 off and on again will crash the system. 


IV-13 


(rev 1) 








V 










valForth Glossary 


Based on the fig-Forth Glossary 
Provided through the courtesy of 
Fourth Interest Group, P.0. Box 1105, San Carlos, CA 94070 


This glossary contains all of the word definitions in Release 1.1 of valForth 
The definitions are presented in the order of their ASCII sort. 

The first line of each entry shows a symbolic description of the action of 
the procedure on the parameter stack. The symbols indicate the order in which input 
pararneters nave been placed on the stack. Two dashes 11 indicate the execution 
point; any parameters left on the stack are listed. In this notation, the top of 
the stack is to the right. 

The symbols include: 

addr memory address 

b 8 bit byte (i.e. hi 8 bits zero) 

c 7 bit ASCII character (hi 9 bits zero) 

32 bit signed double integer, most significant portion with 
sign on top of stack. 

f boolean flag. 0=false, non-zero=true 

boolean true flag=non-zero 
ff boolean false flag=0 

n 16 bit signed integer number 

u 16 bit unsigned integer 

The capital letters on the right show definition characteristics: 

May only be used within a colon definition. A digit indi¬ 
cates number of memory addresses used, if other than one. 

Intended for execution only. 

LO Level Zero definition of FORTH-78 

LI Level One definition of FORTH-78 

Has precedence bit set. Will execute even when compiling, (immediate) 

A user variable. 

A valForth word not in fig-Forth. 

A word adopted from Leo Brodie's Sta rting Forth . 

Unless otherwise noted, all references to numbers are for 16 bit signed integers. 
The high byte of 16 bit numbers is the second byte on the stack, with the sigh in'the 
leftmost bit. For 32 bit signed double numbers, the most significant part (with the 
sign) is on top. 

All arithmetic is implicitly 16 bit signed integer math, with error and under¬ 
flow indication unspecified. 














n addr — 

Store 16 bits of n at address. Pronounced "store". 


Save the stack position in CSP. Used as part of the compiler 
security. 


Generate from a double number dl, the next ASCII character which 
is placed in an output string. Result d2 is the quotient after 
division by BASE, and is maintained for further processing. Used 
between <# and #>. See #S. Pronounced "number". 

d -- addr count Lq 

Terminates numeric output conversion by dropping d, leaving the text 
address and character count suitable for TYPE. Pronounced'"number- 
bracket" . 


Generates ASCiI text in the text output buffer, bv the use of #, 
until a zero double number d2 results. Used between <# and #> 
Pronounced "numbers". 

-- addr p j_Q 

Used in the form: 

1 nnnn 

Leaves the parameter field address of dictionary word nnnn. As a 
compiler directive, executes in a colon-definition to compile the 
address as a literal. If the word is not found after a search of 
CONTEXT and CURRENT, an appropriate error message is given. Pro¬ 
nounced "tick". 


Used in the form: 

*( WORDO W0RD1 . . . WORDN )( WORDN+1 . . .WORDM ) 
which executes as follows: If WORDO is found in a search of CONTEXT 
and CURRENT, then execute W0RD1 . . . WORDM. Generally used for con 
ditional compilation. Note that if no words are to be included in 
the second group, then )( and ) must be separated by at least TWO 
blanks. 


Used in the form: 

( cccc) 

Ignore a comment that will be delimited by a right parenthesis on 
the same line. May occur during execution or in a colon-definition. 
A blank after the leading parenthesis is required. 


No operation. Used in '( constructs. 

V, E ,P 

Scans text input pointer past ")". Used in '( constructs. 

"" . C+ 

The run-time procedure, compiled by ." which transmits the following 
in-line text to the selected output device. See ." 
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(/LOOP) 


(;CODE) 

(+LOOP) 

(ABORT) 

(DO) 

(FIND) 

(FMT) 

(LINE) 

(LOOP) 

(NUMBER) 

(SAVE) 

* 

*/ ' 


n -- 

Execution time code of /LOOP. 


B ,C2 


L 

The run-time procedure, compiled by ;CODE, that rewrites the code 
field of the most recently defined word to point to the following 
machine code sequence. See ;C0DE. 


n — C2 

The run-time procedure compiled by +L00P, which increments the loop 
index by n and tests for loop completion. See +L00P. 


Executes after an error when WARNING is -1. This word normally exe¬ 
cutes ABORT, but may be altered (with care) to a user's alternative 
procedure. 

C 

The run-time procedure'compiled by DO which moves the loop control 
parameters to the return stack. See DO. 


addrl addr2 — pfa b tf (ok) 

addrl addr2 — ff (bad) 

Searches the dictionary starting at the name field address addr2, 
matching to the text at addrl. Returns parameter field address, 
length byte of name field and boolean true for a good match. If no 
match is found, only a boolean false is left. 


nl -- n2 V 

Formats disk in drive nl. Leaves 1 for good format, otherwise error 
number. Note: Because of what appears to be an OS peculiarity, this 
operation must not be the first disk access after a boot. 


nl n2 — addr count 

Convert the line number nl and the screen n2 to the disc buffer address 
containing the data. 


C2 

The run-time procedure compiled by LOOP which increments the loop 
index and tests for loop completion. See LOOP. 

dl addrl — d2 addr2 

Convert the ASCII text beginning at addrl+1 with regard to BASE. 

ihe new value is accumulated into double number dl, being left as d2. 

Addr2 is the address of the first unconvertible digit. Used by NUMBER. 

V 

Used by SAVE, not generally used in programs. Sets up various 
parameters preparatory to writing a bootable disk. 

nl n2 -- prod LO 

Leave the signed product of two signed numbers. Pronounced "star". 

nl n2 n3 -- n4 LO 

Leave the ratio n4 = nl*n2/n3 where all are signed numbers. Retention 
or an intermediate 31 bit product permits greater accuracy than would 
be available with the sequence: 

nl n2 * n3 / 

Pronounced "star-slash". 
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*/MOD 


+ ! 

+- 

+BUF 


+LOOP 


+ORIGIN 


—> 

-DISK 


nl n2 n3 — n4 n5 LO 

Leave the quotient n5 and remainder n4 of the operation nl*n2/n3. 

A 31 bit intermediate product is used as for */. Pronounced "star 
slash-mod". 

nl n2 -- sum LO 

Leave the sum nl+n2. 

n addr -- j_o 

Add n to the value at the address. Pronounced "plus-store". 

nl n2 -- n3 

Apply the sign of n2 to nl, which is left as n3. 
addl — addr2 f 

Advance the disc buffer address addrl to the address of the next 
buffer addr2. Boolean f is false when addr2 is the buffer presently 
pointed to by variable PREV. 

nl -- (run) 

addr n2 — (compile) P,C2,L0 

Used in a colon-definition in the form: 

DO ... nl +L00P 

At run-time, +L00P selectively controls branching back to the corres¬ 
ponding DO based on nl, the loop index and the loop limit. The signed 
increment nl is added to the index and the total compared to the limit. 
The branch back to DO occurs until the new index is equal to or greater 
than the limit (nl>0), or until the new index is equal to or less that 
the limit (nl<0). Upon exiting the loop, the parameters are discarded 
and execution continues ahead. 

At compile time, +L00P compiles the run-time word (+L00P) and the branch 
offset computed from HERE to the address left on the stack by DO. 
n2 is used for compile time error checking. 

n -- addr 

Leave the memory address relative by n to the origin parameter area, 
n is the minimum address unit, either byte or word. This definition 
is used to access or modify the boot-up parameters at the origin area. 

n - LO 

Store n into the next available dictionary memory cell, advancing the 
dictionary pointer, (comma) 

nl n2 — diff LO 

Leave the difference of nl-n2. 

. P,L0 

Continue interpretation with the next disc screen. Pronounced "next- 
screen" . 

addr n2 n3 flag -- n4 V 

Used by R/W. Not generally used in programs. This word performs a 
single-sector read or write on a disk. Addr is the starting RAM 
address, n2 is the sector number (1-720), n3 is the drive number 
(1-4), and the flag is 1 for read and 0 for write. On return, n4 
will be zero if there were no problems, or it will be a DOS error 
number if a DOS error occurred. 
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-DUP 


-FIND 

-TRAILING 


.LINE 

.R 

/ 

/ 

/LOOP 

/MOD 


nl -- nl (if zero) 

nl nl nl (non-zero) LO 

Reproduce nl only if it is non-zero. This is usually used to copy a 

value just before IF, to eliminate the need for an ELSE part to drop 
it. 


-- pfa b tf (found) 

ff (not found) 

Accepts the next text word (delimited by blanks) in the input stream 
to HERE, and searches the CONTEXT and then CURRENT vocabularies for 
a matching entry. If found, the dictionary entry's parameter field 
address, its length byte, and a boolean true are left. Otherwise, 
only a boolean false is left. 

addr nl -- addr n2 

Adjusts the character count nl of a te v t string beginning address to 
suppress the output of trailing blanks, i.e. the characters at 
addr+nl to addr+n2 are blanks. 

n — LO 

Print a number from a signed 16 bit two's complement value, converted 
according to the numeric BASE. A trailing blanks follows. Pronounced 
"dot". 


Used in the form: 


p,lu 


" cccc" 


Compiles an in-line string cccc (delimited by the trailing ") with an 
execution procedure to transmit the text to the selected output device. 
If executed outside a definition, ." will immediately print the text 
until the final The maximum number of characters may’be an installa¬ 
tion dependent value. See (."). 


line scr — 

Print on the terminal device, a line of text from the disc by its line 
and screen number. Trailing blanks are suppressed. 


nl n2 — 

Print the number nl right aligned in a field whose width is n2. No 
following blank is printed. 


nl n2 -- quot 

Leave the signed quotient of nl/n2. 


LO 


n — B,C2 

Like +L00P, but uses an unsigned limit, index, and increment. Thus 
loop index may pass $7FFF without mishap. Faster than +L00P and may 
be used instead of +L00P if increment is positive (and index doesn't 
cross $7FFF.) 

nl n2 — rem quot LO 

Leave the remainder and signed quotient of nl/n2. The remainder has 
the sign of the dividend. 
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0 = 

0 > 

OBRANCH 

1 + 

1 - 

2 * 

2 + 

2 - 
2 / 

2DR0P 

2DUP 

20VER 

2 ROT 

2SWAP 



— n 

These small numbers are used so often that it is attractive to define 
them by name in the dictionary as constants. 

n — flag y 

Leaves a true flag if n is not equal to 0. Otherwise, leaves a false 
flag. Pronounced "zero not equal". 

n — f . L0 

Leave a true flag if the number is less than zero (negative), otherwise 
leave a false flag. 

n - f L 0 

Leave a true flag if the number is equal to zero, otherwise leave a 
false flag. 

n — flag y 

Leaves a true flag if n is greater than 0. Otherwise leaves a false 
flag. 


The run-time procedure to conditionally branch. If f is false (zero), 
the following in-line parameter is added to the interpretive pointer 
to branch ahead or back. Compiled by IF, UNTIL, and WHILE. 

nl -- n2 Li 

Increment nl by 1. 

nl — n2 B 

Subtract one from nl. Pronounced "one-minus". 

nl — n2 B 

Multiply nl by two. Pronounced "two-star" or "two-times". 

nl -- n2 

Leave nl incremented by 2. 
nl - n2 

Leave nl decremented by 2. 

nl — n2 B 

Divide nl by two. Pronounced "two-slash". 


Drops the double number at TOS. 


d — d d B 

Copies double number at TOS. 

d2 dl — d2 dl d2 B 

Copies double number at 20S to TOS. 

d3 d2 dl - d2 dl d3 V 

Moves double number at 30S over two double numbers on 20S and TOS. 

d2 dl — dl d2 B 

Exchanges double numbers at TOS and 20S. 
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p,e,lo 


Used in the form called a colon-definition: 

: cccc ... ; 

Creates a dictionary entry defining cccc as equivalent to the follow¬ 
ing sequence of Forth word definitions '...' until the next or 
;CODE *. The compiling process is done by the text interpreter as long 
as STATE is non-zero. Other details are that the CONTEXT vocabulary 
is set to the CURRENT vocabulary and that words with the precedence 
bit set (P) are executed rather than being compiled. 


;C0DE 


;s 


< 


<# 


<= 


<> 


P,C,L0 

Terminate a colon-definition and stop further compilation. Compiles 
the run-time ;S. 


Used in the form: 

: cccc .... ;C0DE assembly mnemonics 


P,C,L0 


Stop compilation and terminate a new defining word cccc by compiling 
(;CODE). Set the CONTEXT vocabulary to Assember, assembling to machine 
code the following mnemonics. 


When cccc later executes in the form: 
cccc nnnn 

the word nnnn will be created with its execution procedure given by 
the machine code following cccc. That is, when nnnn is executed, it 
does so by jumping to the code after nnnn. An existing defining word 
must exist in cccc prior to ;C0DE. 

P ,L0 

Stop interpretation of a screen. ;S is also the run-time word com¬ 
piled at the end of a colon-definition which returns execution to the 
calling procedure. 

nl n2 — f LO 

Leave a true flag if nl is less than n2; otherwise leave a false 
flag. 


LO 

Set-up for pictured numeric output formatting using the words: 

<# # #S SIGN #> 

The conversion is done on a double number producing text at PAD. 
Pronounced "Bracket Number". 


n2 nl — flag V 

Leaves true flag if n2 is less than or equal to nl. Otherwise, leaves 
false flag. 

n2 nl -- flag V 

Leaves true flag if n2 and nl are unequal. Otherwise, leaves False 
flag. 



<BUILDS 

C,LO 

Used within a colon-definition: 

: cccc <BUILDS ... 

D0ES> ... ; 

Each time cccc is executed, <BUILDS defines a new word with a high- 
level execution procedure. Executing cccc in the form: 
cccc nnnn 

uses <BUILDS to create a dictionary entry for nnnn with a call to the 
D0ES> part for nnnn. When nnnn is later executed, it has the address 
of its parameter area on the stack and executes the words after D0ES> 
in cccc. <BUILDS and D0ES> allow run-time procedures to be written 
in high-level rather than in assembler code (as required by ;C0DE). 

nl n 2 -- f LO 

Leave a true flag if nl=n2; otherwise leave a false flag. 

==> 

If using 512 byte (half-K) screen, does --> otherwise, no 
action is taken. Used to chain screens in half-K format 
that will still load correctly in valFORTH full-K format. 

> 

nl n2 -- f LO 

Leave a true flag if nl is greater than n2; otherwise a false flag. 

>= 

n2 nl — flag V 

Leaves true flag if n2 is greater than or equal to nl. Otherwise, 
leaves false flag. 

>R 

n — C,L0 

Remove a number from the computation stack and place as the most access 
able on the return stack. Use should be balanced with R> in the same 
definition. 

? 

addr — LO 

Print the value contained at the address in free format according to 
the current base. 

? 1K 

— flag V 

Leaves a true flag if C/L is 64, indicating IK screens. Otherwise, 
leaves a false flag. 

7C0MP 

Issue error message if not compiling. 

?CSP 

Issue error message if stack position differs from value saved in CSP. 

TERROR 

f n — 

Issue an error message number n, if the boolean flag is true. 

?EXEC 

Issue an error message if not executing. 

7EXIT 

v,c 

Caution: Use only within a DO LOOP. Within DO LOOP, will cause exit 
at end of current loop if a CONSOLE button is depressed when 7EXIT is 
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?LOADING 

/PAIRS 

/STACK 

/TERMINAL 

@ 

@EX 

ABORT 

ABS 

ACCEPT 

AGAIN 


executed. Will work only in the word in which the DO LOOP is defined, 
not in a word nested further down. 


Issue an error message if not loading, 
nl n2 -- 

Issue an error message if nl does not equal n2. The message indicates 
that compiled conditionals do not match. 


Issue an error message if the stack is out of bounds. This definition 
may be installation dependent. 

— b 

Perform a test of the terminal keyboard for actuation of a CONSOLE 
key. Leaves 0 if none actuated, leaves 1 for START, 2 for SELECT, 

4 for OPTION, and sums for combinations. 

addr -- n LO 

Leave the 16 bit contents of address. 

addr — V 

Fetches the word (presumably a code field address) at addr, and 
then causes it to execute. Used for conditional execution without . 
the speed and memory loss of flags and/or case statements. Typical 
use would be AUXOP @EX where the variable AUXOP had been loaded with 
the cfa of the desired word, by ' DESIREDWORD CFA AUXOP ! . Pro¬ 
nounced “fetch-ex." 


LO 

Clear the stacks and enter the execution state. Return control to 
the operators terminal, printing a message appropriate to the instal¬ 
lation. 

n — u LO 

Leave the absolute value of n as u. 


addr count -- 

Same as EXPECT, except that ACCEPT uses the O.S. line input 
routine which allows full MEMO PAD editing functions to be 
utilized. EXPECT prevents hazards such as Shift-Clear while 
ACCEPT does not. SEE EXPECT. 


addr n — (compiling) P,C2,L0 

Used in a colon-definition in the form: 

BEGIN ... AGAIN 

At-run-time, AGAIN forces execution to return to corresponding BEGIN. 
There is no effect on the stack. Execution cannot leave this loop 
1 unless R> DROP is executed one level below). 

At compile time, AGAIN compiles BRANCH with an offset from HERE to 
addr. n is used for compile-time error checking. 
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ALLOT 


AND 

B/BUF 

B/SCR 

BACK 

BASE 

BEGIN 

BL 

BLANKS 

BLK 

BLOCK 




n — 

Add the signed number to the dictionary pointer DP. 
leserve dictionary space or re-origin memory. 


LO 

May be used to 


nl n2 — n3 

Leave the bitwise logical and of nl and n2 as n3. 

-- n 

This constant leaves the number of bytes per disc buffer thp hvtp 
count read from disc by BLOCK. ’ the byte 

— n 

This constant leaves the number of blocks per editing screen, 
addr — 

inIn U !h! e n!!^ a b ! Ck fr? b ^ nc! ? offset from HERE t0 addr and compile 
into the next available dictionary memory address. 

— addr 

!Uut r conversion? ntal ' n1n ^ the CUrrent nUmber baSe USed for ^ a "« 


P,L0 


-- addr n (compiling) 

Occurs in a colon-definition in form - 
BEGIN ... UNTIL 

BEGIN ... AGAIN 

^ BEGIN ... WHILE ... REPEAT 

exprutPH lme Tt B c GIN marks the Start of 3 se 9 uence That may be repetitively 

a return'tn Rrr?w Ve -if a ret T AGAIN or REPEAT - When executing UNTIL,' 

AfATN InH q pdS N W1 I 0CCUr lf the top of the stack is false; for 
AGAIN and REPEAT a return to BEGIN always occurs. 

error^hecking 6 * BEGIN 163763 1tS return address and n for compiler 


A constant that leaves the ASCII value for "blank" 
addr count — 

Fill an area of memory beginning at addr with blanks. 

— addr _ UJ _ 0 

A user variable containing the block number being interpreted. *lf 
zero, input is being taken from the terminal input buffer. 

n — addr 

Ledve the memory address of the block buffer containing block n. If 
the block is not already in memory, it is transferred from disc to 

thl?, e l e / b u ffe r W3S least recer, tly written. If the block occupying 
Sj r \ b f[ er ha s be f n marked as up-dated, it is rewritten to disc before 
D!ocl< n !S read 1n to the buffer. See also BUFFER, R/W UPDATE FLUSH 




BOOT 

V 

Boots disk in drive 1. Same effect as turning computer on and off. 

BRANCH 

C2 ,L0 

The run-time procedure to unconditionally branch. An in-line offset 
is added to the interpretive pointer IP to branch ahead or back. 

BRANCH is compiled by ELSE, AGAIN, REPEAT. 

BUFFER 

n -- addr 

Obtain the next memory buffer, assigning it to block n. If the con¬ 
tents of the buffer is marked as updated, it is written to the disc. 

The block is not read from the disc. The address left is the first 
byte within the buffer for data storage. 

C! 

b addr -- 

Store 8 bits at address. 

c. 

b — 

Store 8 bits of b into the next available dictionary byte, advancing 
the dictionary pointer.' 

C/L 

V 

A CONSTANT equal to the number of characters per line in the ValForth 
screen. Usually 32, but may be 64 if 1024 byte screens in use. 

C? 

addr — 

Fetches a byte from addr and prints it using . . 

C@ 

addr — b 

Leave the 8 bit contents of memory address. 

CFA 

pfa — cfa 

Convert the parameter field address of a definition to its code 
field address. 

CMOVE 

from to count --- 

Move the specified quantity of bytes beginning at address from to address 
to. The contents of address from is moved first proceeding toward 
high memory. 

COLD 

The cold start procedure to adjust the dictionary pointer to the minimum 
standard and restart via ABORT. May be called from the terminal to 
remove application programs and restart. 

COMPILE 

C2 

When the word containing COMPILE executes, the execution address of 
the word following COMPILE is copied (compiled) into the dictionary. 

This allows specific compilation situations to be handled in addition 
to simply compiling an execution address (which the interpreter al¬ 
ready does). 

CONSTANT 

LO 

A defining word used in the form: 
n CONSTANT cccc 

to create word cccc, with its parameter field containing n. When 
cccc is later executed, it will push the value of n to the stack. 
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CONTEXT 

- addr U,LO 

A user variable containing a pointer to the vocabulary within which 
dictionary searches will first begin. 

COUNT 

addrl — addr2 n LO 

Leave the byte address addr2 and byte count n of a messaae text begin¬ 
ning at address addrl. It is presumed that the first byte at addrl 
contains the text byte count and the actual text starts with the second 
byte. Typically, COUNT is followed by TYPE. 

CR 

LO 

Transmit a carriage return and line feed to the selected output device. 

CREATE 

A defining word used in the form: 

CREATE cccc 

by such words as CODE and CONSTANT to create a dictionary header for 
a FORTH definition. The code field contains the address of the word's 
parameter field. The new word is created in the CURRENT vocabulary. 

CSAVE 

V 

Creates a bootable copy of RAM-resident system up to HERE on cassette. 
Computer beeps twice to indicate user must press Record and Play but¬ 
tons on recorder, prior to pressing RETURN. CSAVE expects leaderless 
tape. If your tape has a leader, wind to just before the end of leader. 

CSP 

-- addr U 

A user variable temporarily storing the stack pointer position, for 
compilation error checking. 

CURRENT 

— addr 

Address of a pointer to second word in the parameter field of the current 
vocabulary. (The current vocabulary is the one to which new definitions 
are added.) 

D! 

d addr — y 

Stores double number d into addr. 

D+ 

dl d2 — dsum 

Leave the double number sum of two double numbers. 

D+- 

dl n — d2 

Apply the sign of n to the double number dl, leaving it as d2. 

D. 

d — LI 

Print a signed double number from a 32 bit two's complement value. 

The high-order 16 bits are most accessable on the stack. Conversion 
is performed according to the current BASE. A blank follows. Pro¬ 
nounced "D-dot." 

D.R 

d n -- 

Print a signed double number d right aligned in a field n characters 
wide. 

DO 

addr — d y 

Fetches double number d from addr. 
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DABS 


DECIMAL 

DEFINITIONS 

DIGIT 

DLITERAL 

DMINUS 

DO 


DOES> 


d — ud 

Leave the absolute value ud of a double number. 

LO 

Set the numeric conversion BASE for decimal input-output. 

LI 

Used in the form: 

cccc DEFINITIONS 

Set the CURRENT vocabulary to the CONTEXT vocabulary. In the example, 
executing vocabulary name cccc made it the CONTEXT vocabulary and exe¬ 
cuting DEFINITIONS made both specify vocabulary cccc. 

c nl — n2 tf (ok) 

c nl -- ff (bad) 

Converts the ASCII character c (using base nl) to its binary equiva¬ 
lent n2, accompanied by a true flag. If the conversion is invalid, 
leaves only a false flag. 

d — d (executing) 

d -- (compiling) P 

If compiling, compile a stack double number into a literal. Later 
execution of the definition containing the literal will push it to 
the stack. If executing, the number will remain on the stack. 

dl — d2 

Convert dl to its double number two's complement, 
nl n2 -- (execute) 

addr n -- (compile) P,C2;L0 

Occurs in a colon-definition in form: 

DO ... LOOP 

DO .. +L00P 

At run-time, DO begins a sequence with repetitive execution controlled 
by a loop limit nl and an index with initial value n2. DO removes 
these from the stack. Upon reaching LOOP, the index is incremented by 
one. Until the new index equals or exceeds the limit, execution loops 
back to just after DO; otherwise, the loop parameters are discarded and 
execution continues ahead. Both nl and n2 are determined at run-time 
and may be the result of other operations. Within a loop "I" will copy 
the current value of the index to the stack. See I, LOOP, +L00P, 
LEAVE. 

When compiling within the colon-definition, DO compiles (DO), leaves the 
following address addr and n for later error checking. 


LO 

A word which defines the run-time action within a high-level defining 
word. DGES> alters the code field and first parameter of the new word 
to execute the sequence of compiled work addresses following D0ES>. 
Used in combination with <BUILDS. When the D0ES> part executes it 
begins with the address of the first parameter of the new word on the 
stack. This allows interpretation using this area or its contents. 
Typical uses include the Forth assembler, multi-dimensional arrays, 
and compiler generation. 

U,L 

A user variable, the dictionary pointer, which contains the address of 
the next free memory above the dictionary. The value may be read by 
HERE and altered by ALLOT, or directTy. 





DPL -- addr U,LO 

A user variable containing the number of digits to the right of the 
decimal on double integer input. It may also be used hold output column 
location of a decimal point, in user generated formatting. The default 
value on single number input is -1. 

DRO 

DR1 

Installation dependent commands to select disc drives, by presetting 
OFFSET. The contents of OFFSET is added to the block number in BLOCK 
to allow for this selection. Offset is supressed for error text so 
that it may always originate from drive 0. 


DROP 

n — 

Drop the number from the stack. 

LO 

DUP 

n — n n 

Duplicate the value on the stack. 

LO 

ELSE 

addrl nl — addr2 n2 (compiling) 

Occurs within a colon-definition in the form: 

IF ... ELSE ... ENDIF 

P,C2 ,L0 


At run-time, ELSE executes after the true part following IF. 

ELSE 


forces execution to skip over the following false part and resumes 
execution after the ENDIF. It has no stack effect. 

At compile-time, ELSE emplaces BRANCH reserving a branch offset, leaves 
the address addr2 and n2 for error testing. ELSE also resolves the 
pending forward branch from IF by calculating the offset from addrl 
to HERE and storing at addrl. 

EMIT c - LO 

Transmit ASCII character c to the selected output device. OUT is 
incremented for each character output. 


EMPTY-BUFFERS LO 

Mark all block-buffers as empty, not necessarily affecting the contents. 
Up-dated blocks are not written to the disc. This is also an initiali¬ 
zation procedure before first use of the disc. Alias is MTB. 

ENCLOSE addrl c -- addrl nl n2 n3 

The text scanning primitive used by WORD. From the text address 
addrl and an ASCII delimiting character c, is determined the byte 
offset to the first non-delimiter character nl, the offset to the first 
delimiter after the text n2, and the offset to the first character 
not included. This procedure will not process past an ASCII "null", 
treating it as an unconditional delimiter. 

END P,C2 ,L0 

This is an "alias" or duplicate definition for UNTIL. 
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ENDIF 


ERASE 

ERROR 


EXECUTE 

EXPECT 

FENCE 

FILL 

FIRST 

FLD 

FORGET 


addr n — (compile) P,CO,LO 

Occurs in a colon-definition in form: 

IF ... ENDIF 
IF ... ELSE ... ENDIF 

At run-time, ENDIF serves only as the destination of a forward branch 
from IF or ELSE. It marks the conclusion of the conditional structure 
THEN is another name for ENDIF. Both names are supported in fig-FORTH 
See also, IF and ELSE. 

At compile-time, ENDIF computes the forward branch offset from addr to 
HERE and stores it at addr. n is used for error tests. 

addr n — 

Clear a region of memory to zero from addr over n addresses, 
n — in blk 

Execute error notification and restart of system. WARNING is first 
examined. If 1, the text of line n, relative to screen 176 of drive 0 
is printed. This line'number may be positive or negative, and beyond 
just screen 176. If WARNING=0> n is just printed as a message number 
(non disc installation). If WARNING is -1, the definition (ABORT) 
is executed, which executes the system ABORT. The user may cautiously 
modify this execution by altering (ABORT). fig-FORTH saves the contents 
of IN and BLK to assist in determining the location of the error. Final 
action is execution of QUIT. 

addr — 

Execute the definition whose code field address is on the stack. The 
code field address is also called the compilation address. 

addr count -- LO 

Transfer characters from the terminal to address, until a "return" or 
the count of characters have been received. One or more nulls are 
added at the end of the text. 

— addr U 

A user variable containing an address below which FORGETting is trapped. 
To forget below this point, the user must alter the contents of FENCE. 

addr quan b -- 

Fill memory at the address with the specified quantity of bytes b. 

— addr 

A constant that leaves the address of the first (lowest) block buffer. 

— addr U 

A user variable for control of number output field width. Presently 
unused in fig-FORTH. 




E,L0 

Executed in the form: 

FORGET cccc 

Delete definition named cccc from the dictionary with all entries 
ohvsicallv following it. 
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FORTH 

FULLK 

GFLAG 

HALFK 

HERE 

HEX 

HLD 

HOLD 

I 

I’ 

ID. 


P,L1 

The name of the primary vocabulary. Execution makes FORTH the CONTEXT 
vocabulary. Until additional user vocabularies are defined, new user 
definitions become a part of FORTH. FORTH is immediate, so it will 
execute during the creation of a colon-definition, to select this voca¬ 
bulary at compile time. 

V 

Sets C/L to 64 and B/SCR to 8, producing 1024 byte screen operation. 

May be SAVEd in this condition. (See HALFK) 

addr V 

A variable that holds a Graphics mode cursor control flag. When the 
value at GFLAG is non-zero, valForth assumes a split-screen is opera¬ 
tive, and will use the alternate cursor-address variables provided by 
the Operating System to use the text window at the bottom of the display 

V 

Sets C/L to 32 and B/SCR to 4, producing 512 byte screen operation. May 
be SAVEd in this condition. (See FULLK) 

— addr ' [_0 

Leave the address of the next available dictionary location. 

L0 

Set the numeric conversion base to sixteen (hexadecimal). 

— addr LO 

A user variable that holds the address of the latest character of 
text during numeric output conversion. 

c -- LO 

Used between <# and #> to insert an ASCII character into a pictured 
numeric output string. 

e.g. 2E HOLD will place a decimal point. 

— n C,L0 

Used within a DO-LOOP to copy the loop index to the stack. Other 
use is implementation dependent. See R. 

— n . B 

Copies the second item on the return stack to the stack. Generally 
used to get the index of the present DO LOOP after an item has been 
pushed to the return stack for convenience. 

addr — 

Print a definition's name from its name field address. 
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IMMEDIATE 

IN 

INDEX 

INTERPRET 

J 

KEY 

KLQAD 


f — (run-time) 

— addr n (compile) P,C2,L0 

Occurs in a colon-definition in form: 

IF (tp) ... ENDIF 

IF (tp) ... ELSE (fp) ... ENDIF 

At run-time, IF selects execution based on a boolean flag. If f is 
true (non-zero), execution continues ahead thru the true part. If f is 
false (zero), execution skips till just after ELSE to execute the false 
part. After either part, execution resumes after ENDIF. ELSE and its 
false part are optional.; if missing, false execution skips to just 
after ENDIF. 

At compile-time IF compiles OBRANCH and reserves space for an offset 
at addr. addr and n are used later for resolution of the offset and 
error testing. 


Mark the most resently made definition so that when encountered at 
compile time, it will be executed rather than being compiled, i.e. 
the precedence bit in its header is set. This method allows defini¬ 
tions to handle unusual compiling situations, rather than build them 
into the fundamental compiler. The user may force compilation of an 
immediate definition by proceeding it with (COMPILED . 

-- addr LO 

A user variable containing the byte offset within the current input 
text buffer (terminal or disc) from which the next text will be ac¬ 
cepted. WORD uses and moves the value of IN. 

from to -- 

Print the first line of each screen over the range from, to. This is 
useo to view the comment (rirst) lines ot an area of text on disc screens. 


I he outer text interpreter which sequentially executes or compiles 
text from the input stream (terminal or disc) depending on STATE. If 
the word name cannot be found after a search of CONTEXT and then CURRENT 
it.is converted to a number according to the current base. That also 
tailing, an error message echoing the name with a " ?" will be given. 
iext input will be taken according to the convention for WORD. If a 
decimal point is found as part of a number, a double number value will 
be ieft. The decimal point has no other purpose than to force this 
action. See NUMBER. 


B 

Copies the third item on the return stack to the stack. Generally 
used to get the index of the next outer DO LOOP. 


- c LO 

Leave the ASCII value of the next terminal key struck. 


screen -- V 

If C/L has a value other than 64, then the number on stack is doubled. 

In either case, LOAD is then executed. The purpose is to allow smart 
conditional loading of either IK screen or 1/2K screen formats. See '(. 
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LABEL 


LATEST 

LEAVE 


LFA 


cccc, 

cccc, -- addr 

At compilation time, creates a word cccc. At run time, cccc leaves 
the address of its pfa on the stack. Used to set up a pointer to the 
following area of memory, as for a machine language subroutine or a 
player image. Examples: 

Example 1: Player image 
2 BASE ! 

LABEL UPARRQW 
00011000 C, 

00111100 C, 

01111110 C, 

00011000 C, 

00011000 C, 

00011000 c, 

OCX 

Example 2: Machine code two-times 
ASSEMBLER 

LABEL 2* 0 ,X ASL, 1 ,X ROL, RTS, 

— addr 

Leave the name field address of the topmost word in the CURRENT voca¬ 
bulary. 

C,L0 

Force termination of a DO-LOOP at the next opportunity by setting the 
loop limit equal to the current value of the index. The index itself 
remains unchanged, and execution proceeds normally until LOOP or +L00P 
is encountered. 

pfa — Ifa 

Convert the parameter field address of a dictionary definition to its 
link field address. 



LIMIT 

LIST 

LIT 

LITERAL 

LOAD 

LOOP 


M* 

M/ 

M/MOD 


— n 

A constant leaving the address just above the highest memory available 
for a disc buffer. 


Display the ASCII text of screen n on the selected output device. 

SCR contains the screen number during and after this process. 

— n C2,L0 

Within a colon-definition, LIT is automatically compiled before each 
16 bit literal number encountered in input text. Later execution of 
LIT causes the contents of the next dictionary address to be pushed 
to the stack. 

n -- (compiling) P,C2,L0 

If compiling, then compile the stack value n as a 16 bit literal. 

This definition is immediate so that it will execute during a colon 
definition. The intended use is: 

: xxx [calculate!] LITERAL ; 

Compilation is suspended for the compile time calculation of a value. 
Compilation is resumed and LITERAL compiles this value. 

n — LO 

Begin interpretation of screen n. Loading will terminate at the end 
of the screen or at ;S. See ;S and —>. 

addr n — (compiling) P,C2,L0 

Occurs in a colon-definition in form: 

DO ... LOOP 

At run-time, LOOP selectively controls branching back to the correspond¬ 
ing DO based on the loop index and limit. The loop index is incremented 
by one and compared to the limit. The branch back to DO occurs until 
the index equals or exceeds the limit; at that time, the parameters are 
discarded and execution continues ahead. 

At compile-time, LOOP compiles (LOOP) and used addr to calculate an 
offset to DO. n is used for error testing. 

nl n2 — d 

A mixed magnitude math operation which leaves the double number signed 
product of two signed numbers. 

d nl — n2 n3 

A mixed magnitude math operator which leaves the signed remainder 
n2 and signed quotient n3, from a double number dividend and divisor 
nl. The remainder takes its sign from the dividend. 

udl u2 — u3 ud4 

An unsigned mixed magnitude math operation which leaves a double quo¬ 
tient ud4 and remainder u3, from a double dividend udl and single 
divisor u2. 

nl n2 -- max 

Leave the greater of two numbers. 


MAX 


LO 



MESSAGE 

MIN 

MINUS 

MOD 

MTB 

NEXT 


NFA 

NOOP 

NOT 

NUMBER 


O+S 

OFF 


n — 

Print on the selected output device the text of line n relative to 
screen 176 of drive 0. n may be positive or negative. MESSAGE may be 
used to print incidental text such as report headers. If WARNING is 
zero, the message will simply be printed as a number (disc unavailable). 

nl n2 -- min LO 

Leave the smaller of two numbers. 

nl — n2 LO 

Leave the two's complement of a number. 

nl n2 -- mod LO 

Leave the remainder of nl/n2, with the same sign as nl. 

V 

Alias of EMPTY-BUFFERS. 

— addr 

This is the inner interpreter that uses the interpretive pointer IP 
to execute compiled Forth definitions. It is not directly executed, 
but is the return point for all code procedures. It acts by fetching 
the address pointed by IP, storing this value in register W. It then 
jumps to the address pointed to by the address pointed to by W. W 
points to the code field of a definition which contains the address 
of the code which executes for that definition. This usage of in¬ 
direct’ threaded code is a major contributor to the power, portability, 
and extensibility of Forth. (Assembler Vocabulary) 

pfa -- nfa 

Convert the parameter field address of a definition to its name field. 

V 

A word that does nothing in minimal time. May be used for reserving 
space in a definition or as a null operation for a word that uses @EX. 
Generally for advanced programmers. Identical to TASK. Pronounced 
"no-op". 

n — flag V 

Leaves a true flag if n is equal to 0. Otherwise, leaves a false flag. 

addr — d 

Convert a character string left at addr with a preceeding count, to 
a signed double number, using the current numeric base. If a decimal 
point is encountered in the text, its position will be given in DPL, 
but no other effect occurs. If numeric conversion is not possible, 
an error message will be given. 

start count — upper-1imit+1 lower-limit V 

Same as OVER + SWAP. Used to set up limits for DO LOOPS and the like. 

V 

A CONSTANT equal to 0. Used to enhance readability. 
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OFFSET 


ON 

OR 

OUT 

OVER 

PAD 

PFA 

PFLAG 

PICK 

POP 

PREV 

PROMPT 

PUSH 


— addr U 

A user variable which may contain a block offset to disc drives. The 
contents of OFFSET is added to the stack number by BLOCK. Messages 
by MESSAGE are independent of OFFSET. See BLOCK, DRO, DR1, MESSAGE. 

V 

A CONSTANT equal to 1. Used to enhance readability. 

nl n2 -- or LO 

Leave the bit-wise logical or of two 16 bit values. 

-- addr U 

A user variable that contains a value incremented by EMIT. The user 
may alter and examine OUT to control display formatting. . 

nl n2 -- nl n2 nl LO 

Copy the second stack value, placing it as the new top. 

-- addr ' LO 


Leave the address of the text output buffer, which is a fixed offset 
above HERE. 

nfa -- pfa 

Convert the name field address of a compiled definition to its para¬ 
meter field address. 

— addr V 

A variable that holds an output-select value. If bit 0 is set then 
output will be sent to the display screen. If bit 1 is set, then output 
will be sent to the printer. If both bits are set, then output will 
go to both channels. 

... n -- ... nl 

Copies the nth entry below n on stack to top of stack. 2 PICK is the 
same as OVER, 1 PICK is the same as DUP. 

— addr 

The code sequence to remove a stack value and return to NEXT. POP is 
not directly executable, but is a Forth re-entry point after machine 
code. (Assembler Vocabulary) 

— addr 

A variable containing the address of the disc buffer most recently 
referenced. The UPDATE command marks this buffer to be later written 
to disc. 


V 

Intended for system use only, in QUIT. A smart version of the usual 
•" ok" in QUIT. Prevents "ok" and visible stack printout from being 
routed to printer. 

— addr 

This code sequence pushes machine Registers to the computation stack 
and returns to NEXT. It is not directly executable, but is a Forth 
re-entry point after machine code. (Assembler Vocabulary) 
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PUT — addr 

This code sequence stores machine register contents over the topmost 
computation stack value and returns to NEXT. It is not directly execu 
table, but is a Forth re-entry point after machine code. 

QUERY 

Input 80 characters of text (or until a "return") from the operators 
terminal. Text is positioned at the address contained in TIB with IN 
set to zero. 


QUIT - L1 

Clear the return stack, stop compilation, and return control to the 
operators terminal. No message is given. 

R — n 

Copy the top of the return stack to the computation stack. 

R# — addr U 

A user variable which may contain the location of an editing cursor, 
or other file related function. 


R/W 


R> 

RO 

REPEAT 


addr blk f - 

The fig-FORTH standard disc read-write linkage, addr specified is the 
source or destination block buffer, blk is the sequential number of 
the referenced block; and f is a flag for f=0 write and f=l read. 

R/W determines the location on mass storage, performs the read-write 

and performs any error checking. Important: See Note 1 at end of glossary. 

— n LO 

Remove the top value from the return stack and leave it on the compu¬ 
tation stack. See >R and R. 

-- addr U 

A user variable containing the initial location of the return stack. 
Pronounced R-zero. See RP! 

addr n — (compiling) p,C2 

Used within a colon-definition in the form: 

BEGIN ... WHILE ... REPEAT 

At run-time, REPEAT forces an unconditional branch back to just after 
the corresponding BEGIN. 


At compile-time, REPEAT compiles BRANCH and the offset from HERE to 
addr. n is used for error testing. 

ROLL ... n -- ... V 

Moves the nth entry below n on stack to top of stack. 3 ROLL is the 
same as ROT, 2 ROLL is the same as SWAP. 0 ROLL is undefined. 

ROT nl n2 n3 — n2 n3 nl LO 

Rotate the top three values on the stack, bringing the third to the 


RP! 

A computer dependent procedure to initialize the return stack pointer 
from user variable RO. 
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RPICK 

S->D 

SAVE 

SO 

SCR 

SGRCTL 

SIGN 

SMUDGE 

SP! 

SP@ 

SPACE 

SPACES 

SPEMIT 


n — V 

Copies nth entry on return stack to parameter (number) stack. For 
instance, 1 RPICK is the same as R and 2 RPICK is the same as I', 
etc. 

n -- d 

Sign extend a single number to form a double number. 

V 

Gives prompt, and if answered with press of "Y" key, moves COLD and 
FENCE parameters to cover current system, makes Forth current, and 
creates a bootable copy of RAM-resident system up to HERE on disk in 
drive 1. 


— addr g 

A user variable that contains the initial value for the stack pointer. 
Pronounced S-zero. See SP! 

-- addr ' y 

A user variable containing the screen number most recently referenced 
by LIST. 


— addr V 

"Shadow Register" for GRACTL, the Atari graphics control register. 
See Atari Operating System Manual for explanation. 


n d LO 

Stores an ASC;I sign just before a converted numeric output 
string in the text output buffer when n is negative, n is discarded, 
but double number d is maintained. Must be used between <# and #>. 




Used during word definition to toggle the "smudge bit" in a definitions 1 
name field. This prevents an uncompleted definition from being found 
during dictionary searches, until compiling is completed without error. 


A computer dependent procedure to initialize the stack pointer from SO. 
— addr 

A computer dependent procedure to return the address of the stack 
position to the top of the stack, as it was before SP@ was executed, 
(e.g. 1 2 SP@ @ . . . would type 2 2 1) 


“ ' LO 

iransmit an ASCII blank to the output device. 

LO 

Transmit n ASCII blanks to the output device. 

V 

Like EMIT, but defined for Atari. Will output control codes as charac¬ 
ters instead of executing the controls. Used by EXPECT and other 
words. 
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TASK 


THEN 


— addr LO,U 

A user variable containing the compilation state. A non-zero value 
indicates compilation. The value itself may be implementation depen¬ 
dent. 


nl n2 — n2 nl 

Exchange the top two values on the stack. 


LO 


A no-operation word which can mark the boundary between applications. 
By forgetting TASK and re-compiling, an application can be discarded 
in its entirety. 


An alias for ENDIF. 


P,C0,L0 


TIB 

TOGGLE 

TRAVERSE 



— addr U 

A user variable containing the address of the terminal input buffer. 

addr b — 

Complement the contents of addr by the bit battern b. 
addrl n — addr2 

Hove across the name field of a fig-FORTH variable length name field, 
addrl is the address of either the length byte or the last letter. 

If n=l, the motion is toward hi memory; if n=-l, the motion is toward 
low memory. The addr2 resulting is address of the other end of the 
name. 


scr -- 

Display on the selected output device the three screens which include 
that numbered scr, beginning with a screen evenly divisible by three. 
Output is suitable for source text records, and includes a reference 
line at the bottom taken from line 14 of screen 177. 



addr count -- LO 

Transmit count characters from addr to the selected output device. 


TYPE as supplied zeroes out the high bit of each character before 
sending it to the output device, usually the screen or printer. 

If you want to be able to type all 8 bits for inverse characters, 
do the following: 

255 ' TYPE 20 + C! 

and return to 7 bit output by doing 

127 1 TYPE 20 + C! 

More generally, 

: 78TYPE < ' TYPE 14 + > C! ; 

: 7TYPE 127 78TYPE j 
: 8TYPE 255 78TYPE ; 

(What you are doing with all of this is changing the mask that 
TYPE uses before executing EMIT.) 


ul u2 -- ud 

Leave the unsigned double number product of two unsigned numbers. 

n — B 

Prints the number n in unsigned form. 


u n -- B 

Prints unsigned number u right justified in a field n wide. 

ud ul -- u2 u3 

Leave the unsigned remainder u2 and unsigned quotient u3 from the 
unsigned double dividend ud and unsigned divisor ul. 


u2 ul — flag V 
Leaves true flag is u2 (unsigned) is greater than ul (unsigned). 
Otherwise, leaves false flag. 




V 


u? 

UNTIL 

UPDATE 

USE 

USER 

VARIABLE 

VOC-LINK 

VOCABULARY 


addr — 

Does a @ from addr and an unsigned print of top of stack. 

f — (run-time) 
addr n -- (compile) P,C2,L0 

Occurs within a colon-definition in the form: 

BEGIN ... UNTIL 

At run-time, UNTIL controls the conditional branch back to the 
corresponding BEGIN. If f is false, execution returns to just after 
BEGIN; if true, execution continues ahead. 

At compile-time, UNTIL compiles (OBRANCH) and an offset from HERE to 
addr. n is used for error tests. 


LO 

Marks the most recently referenced block (pointed to by PREV) as 
altered. The block will subsequently be transferred automatically to 
disc should its buffer be required for storage of a different block. 

— addr 

A variable containing the address of the block buffer to use next, as 
the least recently written. 

n — LO 

A defining word used in the form: 
n USER cccc 

which creates a user variable cccc. The parameter field of cccc 
contains n as a fixed offset relative to the user pointer register 
UP for this user variable. When cccc is later executed, it places 
the sum of its offset and the user area base address on the stack 
as the storage address of that particular variable. 

n " E ,LU 

A defining work used in the form: 
n VARIABLE cccc 

When VARIABLE is executed, it creates the definition cccc with its 
parameter field initialized to n. When cccc is later executed, the 
address of its parameter field (containing n) is left on the stack, 
so that a fetch or store may access this location. 

— addr U 

A user variable containing the address of a field in the definition of 
the most recently created vocabulary. All vocabulary names are linked 
by these fields to allow control for FORGETting thru multiple vocabu¬ 
laries. 


E,L 

A defining word used in the form: 

VOCABULARY cccc 

to create a vocabulary definition cccc. Subsequent use of cccc will 
make it the CONTEXT vocabulary which is searched first by INTERPRET. 

The sequence n cccc DEFINITIONS" will also make cccc the CURRENT voca¬ 
bulary into which new definitions are placed. 

In fig-FORTH, cccc will be so chained as to include all definitions of 
the vocabulary in which cccc is itself defined. All vocabularies ulti¬ 
mately chain to Forth. By convention, vocabulary names are to be de¬ 
clared IMMEDIATE. See VOC-LINK. 
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VLIST 

WAIT 

WARNING 


WHILE 


WIDTH 


WORD 


X 


XOR 

ok 


List the names of the definitions in the context vocabulary. 

V 

Halts execution of Forth until a CONSOLE button is pressed. 

— addr U 

A user variable containing a value controlling messages. If = 1 
disc is present, and screen 176 of drive 0 is the base location for 
messages. If = 0, no disc is present and messages will be presented 
by number. If = -1, execute (ABORT) for a user specified procedure. 
See MESSAGE, ERROR. 

f __ (run-time) 

adl nl -- adl nl ad2 n2 P,C2 

Occurs in a colon-definition in the form: 

BEGIN ... WHILE (tp) ... REPEAT 
At run-time, WHILE selects conditional execution based on boolean 
flag f. If f is true (-non-zero), WHILE continues execution of the 
true part thru to REPEAT, which then branches back to BEGIN. If f 
is false (zero), execution skips to just after REPEAT, exiting the 
structure. 

At compile time, WHILE emplaces (OBRANCH) and leaves ad2 of the re¬ 
served offset. The stack value will be resolved by REPEAT. 

— addr U 

In fig-FORTH, a user variable containing the maximum number of letters 
saved in the compilation of a definitions' name. It must be 1 thru 
31, with a default value of 31. The name character count and its 
natural characters are saved, up to the value in WIDTH. The value may 
be changed at any time within the above limits. 


Read the next text characters from the input stream being interpreted, 
until a delimiter c is found, storing the packed character string 
beginning at the dictionary buffer HERE. WORD leaves the character 
count in the first byte, the characters, and ends with two or more 
blanks. Leading occurances of c are ignored. If BLK is zero, text 
is taken from the terminal input buffer, otherwise from the disc 
block stored in BLK. See BLK, IN. 


This is pseudonym for the "null" or dictionary entry for a name of 
one character of ASCII null. It is the execution procedure to termi¬ 
nate interpretation of a line of text from the terminal or within a 
disc buffer, as both buffers always have a null at the end. 

nl n2 — xor LI 

Leave the bit-wise logical exclusive-or of two values. 

V 

Does three backspaces. When using "logical line input" from keyboard 
to re-input previously entered line, this word gives harmless meaning 
to the old "ok" prompt Forth may find in the input stream. See "logical 
line input" section in Strolling through ValForth. 



P,L1 



Used in a colon-definition in form: 

: xxx C words ] more ; 

Suspend compilation. The words afterCare executed, not comniled. 
This allows calculation or compilation exceptions before resumina* 
compilation with 3. See LITERAL,3 . 


Used in a colon-definition in form: 

: xxx [COMP IL El FORTH ; 

[COMPILE] will force the compilation of an immediate definition, that 
would otherwise execute during compilation. The above example will 
select the FORTH vocabulary when xxx executes, rather than at compile 
time. 


Resume compilation, to the completion of a colon-definition. See C. 



NOTES: 

Note 1 

Due to a bug in at least some of the Atari Operating System ROM programs, 
ci sector may not be written directly from a memory area in which the low 
byte of the bottom location is $7F. The system will hang if this is 

attempted. This is not a valFORTH bug, it is Atari's. Please watch out 
for it. 
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Overview 

Most programming applications can be undertaken completely in high 
level FORTH. There are times, due to speed constraints, when assembly language 
must be used. Typically, "number crunching" and high speed graphic routines 
must be machine coded, valFORTH provides a powerful 6502 FORTH assembler 
for these special occasions. 

FORTH assemblers differ from standard assemblers by making the best use 
of the stack and the FORTH system as a whole. The FORTH assembler is smaller 
than a standard assembler. In the case of the valFORTH assembler, this is 
particularly true. 

The valFORTH assembler offers the programmer the following improvements 
over a standard assembler: 

1) IF...THEN...ELSE structures which use positive logic 
rather than negative logic. 

2) BEGIN...UNTIL structures for post-testing indefinite 
loops. 

3) WHILE...REPEAT structures for pre-testing indefinite 
loops. 

4) BEGIN...AGAIN structures for unconditional looping. 

5) Full access to the FORTH operating system and its 
capabilities such as changing bases. 

6) Complex assembly time calculations. 

7) Mixed high level FORTH with assembly code to take 
full advantage of each. 

8) Full macro capability. 

The following is a complete description of the valFORTH assembler. This 
description assumes a working knowledge of 6502 assembly language proaramminq 
and related terms. 

The purpose of the FORTH assembler is to allow machine language programming 
without the need to abandon the FORTH system. Words coded in assembly language 
must follow the standard FORTH dictionary format and must adhere to certain 
guidelines regarding their coding. 

Assembly language programmers typically have two methods of storing 
programs into RAM. The machine code can be poked directly into memory, or an 
assembler can be used to accomplish this. The former method is brutal, but it 
has the advantage that precious memory is not taken up by the assembler. The 
drawback, of course, is loss of readability and ease of modification. FORTH 
allows both of these methods to be employed. 
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The words and "C," can be used to poke any machine language program 
into the dictionary. This is used only when memory restrictions prohibit the 
use of an assembler or if it is assumed that no assembler is available. 

In high level FORTH, words are compiled into the dictionary using the 
following form: 

: name high-1evel-FORTH... ; 

When compiling a machine coded word, this becomes: 

CODE name machine-code... C; 

In this example, the word "CODE" creates a header for the next word in 
much the same way ":" creates a header. The difference lies in the fact that 
informs the system that the following definition is high level FORTH, while 
"CODE" indicates that the definition is a machine or assembly language 
definition. In the same manner,'";" terminates a high level FORTH definition 
while "C;" terminates a code definition. 

To clarify this, a code definition will be programmed that will clear the 
top line of the current video display on an Atari 800 microcomputer. Note that 
video memory is pointed to by the address stored in locations 88 and 89 (decimal) 
The 6502 code is shown in listing 1. 


CLR 

TYA 

; Y comes in with 0; 0 means a blank 


LDY #39 

; 40 characters/line (0 thru 39) 

LOOP 

STA (88), Y 

; Fill from end to beginning 


DEY 

; Done? 


BPL LOOP 

; Keep going if not 


JMP NEXT 

; Re-enter the FORTH operating system 



Listing 1 

The CODE definition 

equivalent to listing 1 would be: 


HEX 

(put in hex mode) 


CODE CLR 

(define code word) 


98 C, 

(poke in code) 


AO C, 

27 C, 


91 C, 

58 C, «—s 


88 C, 



10 C, 

FB C, —* 


C; DECIMAL (end assembly) 


First, the FORTH system is put into the hexadecimal mode so that opcode 
values need not be converted to decimal. Next, the word CODE puts the system 
into an assembly mode and enters the new word CLR into the dictionary as a 
machine language word. The opcodes are then byte compiled ("C,") into the 
dictionary. Note that for the final jump to re-enter FORTH, the predefined 
word NEXT was word compiled (",") into the dictionary. The word C; terminates 
the assembly process. The system is then restored to the decimal mode. 
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This method can always be used, but it is very tedious. Each opcode must 
be looked up, and all relative branches calculated. Besides introducing a 
great source for error, if a single opcode is added or deleted, it is oossible 
that many jumps must be re-calculated. For this reason, using the assembler 
is the prescribed method for entering machine language routines. 

Unlike the standard assembler which has four fields (the label field, 
the operation field, the operand field, and the comment field), the FORTH 
assembler has only three fields. In a FORTH assembler, there is no explicit 
label field, but there is an implied label field through the use of the assembl 
constructs IF, and BEGIN, described later. In addition, the remaining three 
fields in the FORTH assembler are in reversed order (as is standard for the 
FORTH language). In other words, the operand precedes the operation, and 
remarks can be embedded anywhere. 

In compiling an assembly word, the FORTH assembler ultimately uses either 
V or "C," and for this reason assembly mnemonics traditionally end with a 
comma. valFORTH equivalents are shown in chart 1. 


Standard Assembler 


valFORTH Assembl 

LDX COUNT 


COUNT 

LDX, 

JMP COUNT+1 


COUNT 

1+ JMP, 

LDA #3 


# 3 

LDA, 

ADC N 


N 

ADC, 

STY TOP,X 


TOP ,X 

STY, 

INC B0T,Y 


BOT ,Y 

INC, 

STA (T0P,X) 


TOP X) 

STA, 

AND (BOT),Y 


BOT ) Y 

AND, 

JMP (POINT) 


POINT 

) JMP, 

DEC N+4 


N 4 + 

DEC, 

DEX 



DEX, 

ROL A 


.A 

ROL, 


or 


ROL.A, 

Note: # 9 LDA, = 

9 # 

LDA, 


TOP ,X ROL, = 

,X TOP 

ROL, etc. 



Chart 1 


Converting the program given in listing 1 to FORTH assembly mnemonics 
we have: 

DECIMAL 


CLR 

TYA, 

( 

TYA 

) 

# 39 LDY, 

( 

LDY #39 

) 

BEGIN, 

( LOOP 

) 

88 )Y STA, 

( 

STA (88),Y 

) 

DEY, 


DEY 

) 

MI UNTIL, 

( 

BPL LOOP 

) 

NEXT JMP, 

( 

JMP NEXT 

) 
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In the above example, a BEGIN ... UNTIL, clause (described in the next 
section) is used. By using this structure, no labels are necessary and positive 
logic is used rather than negative logic (i.e., "repeat until minus" instead 
of "if NOT minus, then repeat"). Note that the FORTH assembler compiles 
exactly the same machine code as the standard assembler, it simply makes the 
assembly coding easier. 


Control Structures 

Allowing labels within assembly language programming would make the FORTH 
assembler needlessly long and slow. To get around the problem of test branching, 
the Val FORTH assembler has a very powerful set of control structures similar to 
those found in high level FORTH. 


The IF,. ..ENDIF, and IF,...ELSE,...ENDIF, clauses 


The IF, construct which handles conditional downward branches has the 
following two forms: 

...code... .. .code... 


flag IF, 

...true code... 


flag IF, 

..true code... 


ENDIF, 



...false code... 
ENDIF, 


.. .code... 


-.. .code... 


where "flag" is one of the 6502 statuses: NE , EQ , CC , CS , VC , VS , 

MI , or PL. The following are a few examples of how these are used. 

Note: When the FORTH inner interpreter passes control to an assembly language 
routine, the Y register always contains a zero value and the X register must 

be preserved as it is used by the FORTH system to maintain the parameter stack. 

See the section on parameter passing for more information. 

; Code routine for 1+ 

ONEPL INC 0,X ; increment low byte of 16 bit value 


BNE THERE ; carry out of low? 

INC 1,X ; increment high byte if so 


THERE JMP NEXT ; re-enter FORTH system 


Now in ValFORTH assembly language: 


CODE ONEPL 


0 ,X INC, 
EQ IF, 


1 ,X INC 
ENDIF, 

NEXT JMP, 


(define word) 

(increment low byte) 

(if result was zero,) 
(then bump the high byte) 


(exit to FORTH) 


C; 
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Note: In the following example, CONIN is assumed to be predefined. 


; Input routine 
INPUT JSR CONIN 
CMP #$0D 
BNE INP1 
...codel... 
JMP INP2 

INP1 ...code2... 
INP2 ...code3... 
JMP NEXT 


; Go get character, comes back in A 
; Is it a carriage return? 

; If not, do something else 
; execute code for carriage return 
; do not execute "normal" code 
; execute code for normal keys 
; execute code more common code 
; re-enter FORTH system 


The equivalent valFORTH version would be: 


HEX 

CODE INPUT 

CONIN JSR 
# OD CMP, 

EQ IF, 

...codel... 
ELSE, 

...code2... 
ENDIF, 

...code3... 

NEXT JMP, 

C; DECIMAL 

The BEGIN,...UNTIL, clause 


(Get character ) 
(carriage return? ) 
(If so, then ) 
(execute c/r code ) 
(otherwise ) 


(execute normal code ) 
(re-enter FORTH system ) 


Another useful structure is the BEGIN,...UNTIL, construct which allows 
for post-testing indefinite looping. The BEGIN,...UNTIL, construct has the 
following form: 

...codel... 

BEGIN, code2 is repeatedly 

...code2... executed until "flag" 

flag UNTIL, is true. 

...code3... 


The following 6502 routine waits until a carriage return has been typed. 
; WAIT until c/r 

WAIT JSR CONIN ', Go get a character, comes back in A 

CMP #$0D ; Is it a carriage return? 

BNE WAIT ; Ask again if not 

JMP NEXT ; Return to FORTH 


Using the BEGIN, clause, this becomes 


NEXT 

CODE WAIT 
BEGIN, 

CONIN JSR, 
# OD CMP, 
EQ UNTIL, 

NEXT JMP, 

C; DECIMAL 


(Code name WAIT ) 
(Begin waiting ) 
(Get a character ) 
(Carriage return?) 
(loop up until so) 
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The BEGIN,...WHILE,...REPEAT, clause 

In the valFORTH assembler, there is another valuable control structure. 
It is the BEGIN,...WHILE,...REPEAT, structure. The WHILE, clause allows pre¬ 
testing indefinite loops to be easily programmed. It takes the form: 


...codel... 
BEGIN, 

...code2... 
flag WHILE, 

...code3... 
REPEAT, 

...code4... 


Code2 and code3 are repeatedly 
executed until "flag" become 
false, at which time program 
control proceeds to code4. 


A corranon example of the WHILE, clause is getting a line of input text terminated 
by a carriage return. 


; Get line of text 
GETLN JSR CONIN 
CMP #$0D 
BEQ GETL1 
STA BFFR,Y 
INY 

JMP GETLN 
GETL1 JMP NEXT 


(note: Y=0 on entry always) 
; Get one character 
; C/R terminates input 
; If not a C/R then 
; store the character 
; Bump buffer pointer 
; Go back for more 
; Exit to FORTH 


Using the WHILE, clause in valFORTH, we have: 


HEX 

CODE GETLN 
BEGIN, 

CONIN JSR, 

# OD CMP, 

NE WHILE, 

BFFR ,Y STA, 
INY, 

REPEAT, 

NEXT JMP, 

C; DECIMAL 


(Get a character 
(Carriage return? 

(If not, ) 
(then store the character } 
(and bump the pointer ) 
(Repeat all of the above ) 
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The BEGIN,...AGAIN, clause 


The final control structure is the BEGIN,...AGAIN, structure. This 
structure allows the use of unconditional looping in assembly language routines. 
Although its use is rare, it can reduce code size considerably. It takes the 
following form: 


...codel... 

BEGIN, 

...code2— 
flag IF, 

...code3... 
re-entry-point JMP, 
ENDIF, 

...code4... 

AGAIN, C; 


Repeatedly execute code2 
and code4 until "flag" 
becomes true, in which 
case, program execution 
continues with code3 and 
a system re-entry made. 


The best example of the AGAIN, clause is in the coding of the CMOVE routine: 


; Byte at a time front end 
CMOVE LDA #3 ; 

JSR SETUP 

CM0V1 CPY N ; 

BNE CM0V2 ; 

DEC N+l ; 

BPL CM0V2 ; 

JMP NEXT ; 

CM0V2 LDA (N+4),Y ; 

STA (N+2),Y ; 

INY ; 

BNE CM0V1 

INC N+5 ; 

INC N+3 ; 

JMP CM0V1 ; 


memory move 

Get top three stack items 
Move them to N scratch area 
Time to decrement COUNT high? 
Nope 

Yes, so do it 
Bypass exit if not done 
Exit to FORTH system 
Get byte to move 
Move it! 

Bump byte pointer 
Keep going until ready to 
bump high bytes of both 
"to" and "from" addresses 
Do it all again 


Using the AGAIN, clause, this becomes: 


CODE CMOVE 
# 3 LDA, 

SETUP JSR, 

BEGIN, 

BEGIN, 

N CPY, 

EQ IF, 

N 1+ DEC, 

MI IF, 

NEXT JMP, 
ENDIF, 

ENDIF, 

N 4 + )Y LDA, 

N 2+ )Y STA, 
INY, 

EQ UNTIL, 

N 5 + INC, 

N 3+ INC, 

AGAIN, 

C; DECIMAL 


(Prepare for memory move) 

(Start the process) 
(done?) 

(Maybe, keep checking) 
(Re-enter FORTH system) 

(Get byte to copy) 

(Store in new location) 
(Bump pointer) 

(Bump addresses) 

(Do it all again) 
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Parameter Passing 

One of the most useful features of the FORTH language is its ability to 
use a parameter stack for passing values from one word to another. For 
assembly language routines to really be useful in the FORTH system, there must 
be some facility for these routines to access this stack. Likewise, there 
should be some way in which to access the return stack as well. This section 
details exactly how to make the best use of both stacks. 

Since the FORTH system maintains dual stacks and the 6502 supports only 
one, it is necessary to simulate one of the stacks. For ease of stack manipu¬ 
lation, the parameter is simulated; the return stack uses the hardware stack 
of the microprocessor. 

The simulated stack uses the 0-page,X addressing mode of the 6502. 

For example, the following statements show how the parameter stack is organized. 


LDA 

0, 

,X 

Low byte of 

item 

on top of stack 

INC 

1 . 

,x 

High byte of top 

item 

ADC 

2. 

,x 

Low byte of 

item 

second on stack 

EOR 

3- 

,x 

High byte of 20S 


RNL 

4, 

,x 

Low byte of 

item 

third on stack 

AND 

5. 

,x 




etc. 


In high level FORTH, the word DROP drops (or pops) the top value from 
the stack. The code definition for DROP is: 

CODE DROP INX, INX, NEXT JMP, C; 

In the same way, values can be "pushed" to the stack. Note that the X register 
must be preserved between FORTH words or the parameter stack is lost! Thus if 
the X register is needed in a code definition, it must be saved upon entry to 
the routine and restored before returning to the FORTH system. The special 
location XSAVE is reserved for this: (The word XSAVE has been defined as a 
FORTH constant.) 

STX XSAVE Save the X register 

LDX XSAVE Restore the X register 

In all the examples given so far, the code definitions have re-entered 
the FORTH system through the normal re-entry point called NEXT. The following 
is a complete description of all possible re-entry points: (In all of the 
following code examples, standard 6502 assembler format has been used for ease 
of comprehension. All valFORTH assembler equivalents can be found in appendix A.) 

The NEXT re-entry point 

The NEXT routine transfers control to the next FORTH word to be 
executed. All FORTH words eventually come through the NEXT routine. 

Likewise, all other re-entry points come through NEXT once they have com¬ 
pleted their special tasks. The next routine is typically used by words 
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The NEXT re-entry point (cont'd) 

such as 1- which do not modify the number of arguments on the 


stack. 

The word NEXT is 

defined as a FORTH constant. NXT 

abbreviation for NEXT JMP 

> 

Example: 

; 1- routine 

ONEM LDA 0,X 

; Borrow from low byte? 


BNE 0NE1 

; If not, ignore correction 


DEC 1,X 

; Decrement high byte 


0NE1 DEC 0,X 

; Now do the low 


JMP NEXT 

; Re-enter FORTH 



Listing 2 


The PUSH re-entry point : 

The PUSH routine pushes a 16 bit value to the parameter stack whose 
low byte is found on the 6502 return stack and whose high byte is found 
in the accummulator. The X register is automatically decremented twice 
for the two bytes. This routine is typically used for words such as 
OVER or DUP which leave one more argument than they expect. The word 
PUSH has been defined as a FORTH constant. PSH, is an abbreviation 
for PUSH JMP, . 


Example: ; DUP routine 

DUP IDA 0,X 
PHA 

LDA 1,X 
JMP PUSH 


; Get low byte of TOS 
; Push it 

; Put high byte in A 
; Put it on the P-stack 


Listing 3 


The PUT re-entry point : 


The PUT routine replaces the value currently on top of the parameter 
stack with the 16 bit value whose low byte is found on the 6502 stack and 
whose high byte is in the accumulator. This is used by words such as ROT 
or SWAP which do not change the number of values on the stack. The word 
PUT has been defined as a FORTH constant. PUT, is an abbreviation for 
PUT JMP, . 


Example: ; SWAP routine 


SWAP LDA 

X 

CVl 

PHA 


LDA 

o,x 

STA 

2,X 

LDA 

3,X 

LDY 

1,X 

STY 

3,X 

JMP 

PUT 


; Low byte of 2nd value 
; Save it 

; Put low byte of TOS 
; into low byte of 20S 
; Hold high byte of 20S 
; Put high byte of TOS 
; into high byte of 20S 
; Replace TOS no 


Listing 4 
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The PUSHOA re-entry point 

The PUSHOA re-entry point pushes the 8 bit unsigned value in the 
accumulator as a 16 bit value with the upper 8 bits zeroed. This word is 
very commonly used by words which leave a boolean flag on the parameter 
stack such as 7TERMINAL. The word PUSHOA has been defined as a FORTH 
constant. PSHA, is an abbreviation for PUSHOA JMP, . 


Example: 


; 7TERMINAL routine 
QTERM LDA $D01F 
EOR #7 
BEQ QT1 
IN Y 

QT1 TV A 

JMP PUSHOA 


Read Atari CONSOLE keys 
Anything pressed? 

If not, go push false 
Else push a true 
Put Y (0 or 1) in A 
Go push the result 


Listing 5 


The PUTOA re-entry point : 

The PUTOA routine replaces the value currently on top of the parameter 
stack with the 16 bit value whose low byte is in the accumulator and whose 
high byte is set to zero. This is used by words such as C@ which simply 
replace their arguments on the stack. The word PUTOA is defined as a FORTH 
constant. PUTA, is an abbreviation for PUTOA JMP, . 

Example: ; Byte fetch 

CFCH LDA (0,X) ; Load byte indirectly 

JMP PUTOA ; Replace the address 
; with the contents 

Listing 6 

The BINARY re-entry point 

The BINARY re-entry point drops the value on top of the parameter 
stack and then performs the PUT operation described above. This word is 
commonly used by words such as XOR which use one more argument than they 
leave. The word BINARY has been defined as a FORTH constant. 


Example: 


XOR 


Exclusive or TOS with 20S 


LDA 

0,X 

EOR 

2,X 

PHA 


LDA 

1,X 

EOR 

3,X 

JMP 

BINARY 


; Get low byte of 
; XOR it with low 
; Save it 
; Now do same for 
; Result in A 
; Go DROP , PUT 


top value 
of 20S 

high bytes 


Listing 7 
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POP and POPTWO re-entry points 

The POP and POPTWO re-entry points are used when values must be 
dropped from the parameter stack. POP performs a DROP, while POPTWO 
performs a 2DR0P. Most words which can use BINARY can use POP. The words 
POP and POPTWO have been defined as FORTH constants. POP, is an 
abbreviation for POP JMP, and POP2, is an abbreviation for POPTWO JMP, . 


Examples: ; Another XOR routine 


XOR LDA 0,X 
EOR 2,X 
STA 2,X 
LDA 1,X 
EOR 3,X 
STA 3,X 
JMP POP 


; C! routine 
CSTR LDA 2,X 
STA (0,X) 
JMP POPTWO 


The SETUP routine 


; Get low byte 
; XOR with other low byte 
; Put directly on stack 
; Do the same for high bytes 


; Remove unneeded TOS item 
Listing 8 


; Get byte to store 
; Store it! 

; Drop byte and address 
Listing 9 


A very useful routine in the FORTH system is the code routine SETUP. 

On the 6502, 0-page addressing is typically faster than absolute address¬ 
ing. Also, some instructions, such as indirect-indexed addressing, can use 
only 0-page addresses. The SETUP routine allows the assembly language 
programmer to transfer up to four stack values to a scratch pad in the 
0-page for these operations. The predefined name for this area is N. 

The calling sequence for the SETUP routine is: 


LDA #num ; Move "num" values to N, ("num" = 1-4) 

JSR SETUP ; then drop "num" values from the stack 


The SETUP routine moves one to four values to the N scratch area 
and drops all values moved from the parameter stack. These values are 
stored in the following order: 

LDA N ; Low byte of value that was TOS 

EOR N+l ; High byte ( N 1+ EOR, ) 

ADC N+2 ; Low byte of value that was 20S 

STY N+3 ; High byte ( N 3 + STY, ) 

INC N+4 ; Low byte of 30S ( N 4 + INC, ) 

DEC N+7 ; High byte of value that was 40S 

Words such as CMOVE and FILL which use indirect-indexed addressing 
typically use the SETUP routine (see the BEGIN,...AGAIN, example). The 
word SETUP has been defined as a FORTH constant. 
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Return stack manipulation 


The FORTH return stack is implemented as the normal 6502 hardware 
stack. To push and pop values, the 6502 stack instructions PHA and PLA 
can be used. Sometimes it is also necessary to manipulate the data on the 
return stack (such as for DO looping). Using the normal stack operations 
to do this can be tedious. Using indexed addressing, the return stack 
can be manipulated in the same manner as the parameter stack. 


Examples: ; >R routine 
TOR LDA 1,X 
PHA 

LDA 0,X 
PHA 

JMP POP 


; 3rd loop index 
K STX XSAVE 
TSX 

LDA $109,X 
PHA 

LDA $10A,X 
LDX XSAVE 
JMP PUSH 


Machine Language Subroutines in 


; Pick up high byte 
; Push it to R 
; How do the low byte 
; It's done! 

; Now, "lose" TOS 

Listing 10 

I , I' , J , ... K ) 

; Save P-stack pointer 
; Get R-stack pointer 
; 101-102,...,109-10A, (L-H) 
; Push low byte of 3rd item 
; A now has high byte 
; Restore P-stack pointer 
; Push the index 

Listing 11 


FORTH 


When coding in assembly language, it is often useful to be able to make 
subroutine calls for often used operations. Using CODE makes it possible to 
do this, but it is not recommended. The following subroutine uses CODE. 


CODE S1+ 

0 ,X INC, 

EQ IF, 

1 ,X INC, 
ENDIF, 

RTS, 

C; 


( Subroutine 1+ ) 

( INC 0,X ) 

( BNE *+4 

INC 1,X 

RTS ) 


This subroutine could now be used in assembly language routines in the follow¬ 
ing way: 

CODE 1+ (Another 1+ routine ) 

' S1+ JSR, ( JSR S1+ 

NEXT JMP, ( JMP NEXT ) 

C; 
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This works fine, but there is one slight problem. If the user types S1+ as a 
command (i.e., it is not called, but executed) the FORTH system will "crash" 
when the RTS statement is encountered. This is because FORTH does not call its 
words, but jumps to them. For this reason, CODE is not used. A word which 
acts like CODE but protects the system is needed. 


In the code for 1+ above, it was necessary to ' (tick) the subroutine to 
find its address. It would be desirable if we could simply type its name and 
have it return its address (just as NEXT and PUSH do). This is possible. The 
word SUBROUTINE below allows this (note that this word is not automatically 
loaded with the assembler, it must be typed in by the user). 


: SUBROUTINE 
0 VARIABLE 
-2 ALLOT 

[COMPILE] ASSEMBLER 
?EXEC iCSP ; 


(new word SUBROUTINE ) 
(is like a VARIABLE ) 
(discard the value of 0 ) 
(Put into assembly mode ) 
(Set/check for errors ) 


The word SUBROUTINE can be used in the same way CODE is except that 
SUBROUTINES end with an RTS instruction while CODE routines must end with a 
jump to a re-entry point. When the word defined using SUBROUTINE is executed, 
the entry point to the routine is left on the stack similar to the way in which 
a word defined using VARIABLE leaves an address. The following is an example 
of subroutine usage. 


SUBROUTINE 2'SCOMP 
SEC, 

0 # LDA, 

0 ,X SBC, 

0 ,X STA, 

0 # LDA, 

1 ,X SBC, 

1 ,X STA, 

RTS, 

C; 


(Two's complement ) 
(routine ) 

(i.e., TOS => - TOS) 


It can now be used as such: 


CODE ABS 

1 ,X LDA, 

MI IF, 

2'SCOMP JSR, 
ENDIF, 

NEXT JMP, 


(Take abs. value of TOS ) 
(Is TOS < 0 ? ) 

(If so, TOS => -TOS ) 

(Exit to FORTH system ) 


When the new word 2'SCOMP is executed directly, it leaves its address 
on the stack. When it is called by a subroutine, it performs a two's comple¬ 
ment on the top stack value. This dual type of execution allows safe access 
to assembly language subroutines. 
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Macro Assemblies in valFORTH 

FORTH assemblers use a reversed form of notation so that all the benefits 
of the standard FORTH system are available. In other words, anything that can 
be done in FORTH can be done during assembly time in a code definition. This 
is because all of the assembler opcodes are actually FORTH words which take 
arguments from the parameter stack. Thus 


NEXT JMP, 

actually puts the address of the NEXT routine (NEXT is a FORTH constant) onto 
the parameter stack. The word JMP, then compiles the address into the dictionary. 
Here is a simplified definition (it does not test for indirect jumping) for the 
JMP, opcode: 


HEX 
: JMP, 

4C C, 

■, DECIMAL 


(address — ) 

(compile in JMP opcode ) 
(compile in the address ) 


Ail assembly words are designed in this fashion. Thus the necessity for 
operands to precede opcodes becomes clear,, This allows the use of complex 
assembly time calculations that no ordinary assembler would ever support (e.g. 
no standard 6502 assembler would allow the use of the SIN function for generat¬ 
ing a data table). 


Most assemblers do allow the use of the basic operations: + 
and &. These are easily used in the valFORTH system: 


LDA #C0UNT&$FF 
LDY #NAME/$100 
EOR N+6 
LDX #"A"+$80 
etc. 


COUNT FF AND # LDA, 
COUNT 100 / # LPY, 

N 6 + EOR, 
ASCII A 80 + # LDX, 



The looping structures IF, and BEGIN, each leave two values on the stack 
during assembly time. The first is a branch address, the second is an identifi¬ 
cation code. When ENDIF, is executed, it checks the identification code to 
verify that structures have not been illegally interleaved (i.e., BEGIN, ... 
ENDIF, ). If everything checks out, ENDIF, then calculates the branch offset 
required by the IF, clause, otherwise an error is reported. The BEGIN, clause 
functions in the same manner. Thus, the words IF, and BEGIN, are predefined 
macro instructions in the valFORTH assembler. 


The fact that a-FORTH assembler is nothing but a collection of words means 
that the assembler, like the FORTH language itself, is extensible. In other 
words, macro assemblies can easily be performed by defining new assembler 
directives. Take the following code extract which outputs a text string: 
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...code... 

JSR CRLF 
JSR PRTXT 

.BYTE 11,’valFORTH 1.' 
IDA REL 
JSR PRTNM 
JSR CRLF 
...code... 


Skip to next line 
Call print routine 
String to output 
Get release number 
Print the number 
Issue c/r 


This code prints out the string "valFORTH 1.x" where "x" is the release 
number. Note that the routine PRTXT does not exist, it is simply used here 
for example purposes. The PRTXT routine "pops" the return address which points 
to the output string, picks up the length byte and adds it to the return address. 
The return address, which now points to the LDA instruction is "pushed" back 
onto the stack. The PRTXT routine still has a pointer to the string which it 
then prints out. Finally, it dones an RTS and returns control to the calling 
program. The release number is then printed out. 


Assuming that the PRTXT routine is used quite often, it would be desirable 
to make it an assembler macro. A word which automatically assembles in the 
subroutine call to PRTXi and then assembles in a user specified string would be 
quite handy. In val FORTH, this is easily accomplished: 


ASSEMBLER DEFINITIONS 
HEX 

: PRINT" 

20 C, PRTXT , 

22 WORD 

HERE CO 1+ ALLOT 
; DECIMAL 
IMMEDIATE 
FORTH DEFINITIONS 


(This is an assembler word) 
(Put system in base 16) 
(Command form: PRINT" text") 
(compile in JSR PRTXT) 

(Now the string upto ") 

(Bump dictionary pointer) 

(all done,) 

(make word execute even at) 
(compile time.) 


This word could now be used in ValFORTH assemblies in the following manner: 


...code... 

CRLF JSR, (Skip to next line) 

PRINT" ValFORTH 1." (Print out string) 

REL LDA, (Get release number) 

PRTNM JSR, (Go print it) 

CRLF JSR, (Skip to next line) 

...code... 

Using the newly defined PRINT" macro, strings no longer need to be counted, 
and since there is less text to enter, typing errors are reduced. Other useful 
macros which could be designed are words which allow conditional assembly or 
automatically set up IOCB blocks for Atari operating system calls. Experienced 
assembly language programmers typically have a set of often used routines 
defined as macro instructions for quicker program development. 
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Compatability With Other Popular Assemblers 

There are several other versions of FORTH out which have 6502 assemblers. 
The two major versions are the Forth Interest Group's written by William 
Ragsdale, and the version put out by the Atari Program Exchange written by 
Patrick Mullarky. The valFORTH assembler is a superset of both of these fine 
assemblers and is fully compatible with both versions . 

Although not stated previously in the documentation, there are several 
ways in which to implement the IF, , WHILE, and UNTIL, structures. The 
valFORTH assembler was designed with transportability in mind. Although the 
recommended method is the valFORTH version, each of the following may be used . 


valFORTH 

Fig version 

APX version 

EQ IF, 

0= IF, 

IFEQ, 

NE IF, 

0= NOT IF, 

IFNE, 

CS IF, 

CS IF, 

IFCS, 

CC IF, 

CS NOT IF, 

IFCC, 

VS IF, 


IFVS, 

VC IF, 


IFVC, 

MI IF, 

0< IF; 

IFMI, 

PL IF, 

0< NOT IF, 

I FPL, 

EQ WHILE, 

NE WHILE, 

CC WHILE, 

CC WHILE, 

VS WHILE, 

VC WHILE, 

MI WHILE, 

PL WHILE, 

EQ UNTIL, 



U. m. M. — i. 




0= UNTIL, 

0= UNTIL, 

NE UNTIL, 

0= NOT UNTIL, 

0= NOT UNTIL, 

CS UNTIL, 

CS UNTIL, 


CC UNTIL, 

CS NOT UNTIL, 

---- 

VS UNTIL, 



VC UNTIL, 



MI UNTIL, 

0< UNTIL, 


PL UNTIL, 

0< NOT UNTIL, 



Chart 2 
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In all versions, the word END, is synonymous with the word UNTIL,. Likewise, 
THEN, is synonymous with ENDIF,. 

In the valFORTH and Fig assemblers, compiler security is performed to give 
added protection to the user against assembly errors. To accomplish this, the 
word C; or its synonym END-CODE is used to terminate the assembly word and 
perform the check. To remain compatible with AFX FORTH, C; is not required in 
this release of valFORTH. However, it is strongly recommended that C; be 
used. Although C; and END-CODE are identical, C; is used in-house at Valpar 
tor brevity. (Note that in later releases of valFORTH, C; will become mandatory). 

There are several ways in which the indirect jump in the 6502 architecture 
is implemented in FORTH assemblers. The valFORTH assembler supports three 
common versions. Thus, 


JMP (VECTOR) 

can be: 

VECTOR )JMP, 

VECTOR ) JMP, 
or VECTOR JMP(), 

It is recommended that the first version be used. 

It must be remembered that valFORTH's additional constructs may not be 
recognized by assemblers available from other vendors. If assembly listings 
are to be published for general 6502 FORTH users, it is suggested that valFORTH's 
advanced features not be used so that novice programmers can still make use of 
valuable pieces of code. 
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Appendix A valFORTH Code Equivalents 

This appendix gives the valFORTH assembly code for all 6502 code listings 
which are marked. Although listing 1 has already been translated to valFORTH 
assembly code, it is reproduced here for completeness. 


Listing 1 


DECIMAL 
CODE CLR 
TYA 

# 39 LDY, 
BEGIN, 

88 )Y STA, 
DEY, 

MI UNTIL, 

NEXT JMP, 


(Move a blank [0] into A) 
(Move count into Y) 

(Start looping) 

(Move in a blank) 
(decrement pointer) 

(Go until count < 0) 

(Do a normal re-entry) 


Listing 2 


CODE 


C; 


Listing 3 
CODE 


C; 


1- 

(Decrement 16 bit value) 

0 ,X LDA, 

(Get the low byte) 

NE IF, 

(If a borrow will occur,) 

1 ,X DEC, 

(then borrow from high... 

ENDIF, 


0 ,X DEC, 

(Decrement low) 

NEXT JMP, 

(Re-enter FORTH) 


DUP 

(Duplicate TOS) 

0 ,X LDA, 

(Get low byte) 

PHA, 

(Set up for PUSH) 

1 ,X LDA, 

(Put high in Accumulator) 

PUSH JMP, 

(Push 16 bit value) 


Listing 4 


CODE 


SWAP 

(Exchange top stack items) 

2 ,X LDA, 

(Get low byte of 20S) 

PHA, 

(Save it) 

0 ,X LDA, 

(Put low byte of TOS) 

2 ,X STA, 

( into low byte of 20S 

3 ,X LDA, 

(Save high byte of 20S) 

1 ,X LDY, 

(Put high byte of TOS) 

3 ,X STY, 

( into high byte of 20S) 

PUT JMP, 

(Put old 20S into TOS) 


C; 
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Listing 5 


HEX 

CODE ?TERMINAL 
D01F LDA, 
# 7 EOR, 


(Any console key pressed?) 
(Load status byte) 

(Any low bits reset? 



NE IF, 

(If so,) 


INY, 

ENDIF, 

(then leave a true value) 


TYA, 

(Put true or false into A) 


PUSHOA JMP, 

(Push to parameter stack) 

C; 

DECIMAL 


i ng 

6 


CODE C@ 

(Byte fetch routine) 


0 X) LDA, 

(Load from address on TOS) 

C; 

PUTOA JMP, 

(Push byte value) 


Listing 7 



CODE XOR 

0 ,X LDA, 

2 ,X EOR, 
PHA, 

1 ,X LDA, 

3 ,X EOR, 
BINARY JMP, 

C; 


Listing 8 


CODE XOR 

0 ,X LDA, 


2 ,X EOR, 

2 ,X STA, 
1 ,X LDA, 

3 ,X EOR, 
3 ,X STA, 
POP JMP, 


C; 

Listing 9 


CODE C! 

2 ,X LDA, 

0 )X STA, 
POPTWO JMP, 
C; 


(One example of XOR) 

(Get low byte of TOS) 
(Exclusive or it with 20S) 
(Push low result) 

(Get high byte of TOS) 

(XOR it with high of 20S) 
(Drop TOS and replace 20S) 


(Another exclusive or) 
(Get low byte of TOS) 
(XOR with low of 20S) 
(Put in low of 20S) 
(Get high byte of TOS) 
(XOR with high of 20S) 
(Put in high of 20S) 
(Drop TOS) 


(Byte store routine) 
(Pick up byte to store) 
(Indirectly store it) 
(Drop address and byte) 
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Listing 10 

CODE >R 

1 ,X LDA, 
PHA, 

0 ,X LDA, 
PHA, 

POP JMP, 


(Transfer TOS to R-stack) 
(Pick up high of TOS) 

(Put on R-stack) 

(Pick up low of TOS) 

(Put on R-stack) 

(Lose top stack item) 


Listing 11 


HEX 

CODE K 

XSAVE STX, 
TSX, 

109*,X LDA, 
PHA, 

10A ,X LDA 
XSAVE LDX, 
PUSH JMP, 

C; DECIMAL 


(3rd inner DO loop index) 
(Save P-stack pointer) 

(Pick up R-stack pointer) 
(Pick up low byte of value) 
(Save it) 

(Put high byte of value in A) 
(Restore P-stack pointer) 
(Push 16 bit index value) 
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Appendix B 


Quick Reference Chart 


valFORTH 6502 Assembly Words 

ASSEMBLER ( --- ) 

Calls up the assembler vocabulary for subsequent assembly language 
programming. 

CODE cccc ( — ) 

Enters the new word "cccc" into the dictionary as machine language 
word and calls up the assembler vocabulary for subsequent assembly language 
programming. CODE also sets the system up for security checking. 


C; ( — ) 

Terminates an assembly language definition by performing a security 
check and setting the CONTEXT vocabulary to the same as the CURRENT 
vocabulary. 

END-CODE ( — ) 

A commonly used synonym for the word C; above. The word C; is 
recommended over END-CODE. 

SUBROUTINE cccc ( — ) 

Enters the new word "cccc" into the dictionary as machine language 
subroutine and calls up the assembler vocabulary for subsequent assembly 
language programming. SUBROUTINE also sets the system up for security 
checking. 


;C0DE { — ) 

When the assembler is loaded, puts the system into the assembler 
vocabulary for subsequent assembly language programming. See main 
glossary for further explanation. 


Control Structures 


IF, ( flag — addr 2 ) 

Begins a machine language control structure based on the 6502 status 
flag on top of the stack. Leaves an address and a security check value 
for the ELSE, or ENDIF, clauses below, "flag" can be EQ , NE , CC , CS , 
VC , VS , MI , or PL . Command forms: 

... flag..IF,..if~true..ENDIF,.. .all... 

...flag..IF,..if-true..ELSE,..if-false..ENDIF,..all... 
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ELSE, ( addr 2 — addr 3 ) 

Used in an IF, clause to allow for execution of code only if IF, 
clause is false. If the IF, clause is true, this code is bypassed. 

See IF, above for command form. 


ENDIF, ( addr 2/3 — ) 

Used to terminate an IF, control structure clause. Additionally, 
ENDIF, resolves all forward references. See IF, above for command form. 

BEGIN, ( — addr 1 ) 

Begins machine language control structures of the following forms: 

...BEGIN,...AGAIN,... 

...BEGIN,...flag..UNTIL,... 

...BEGIN,...flag..WHILE,..while-true..REPEAT,... 

where "flag" is one of the 6502 statuses: EQ , NE , CC , CS , VC , 

VS , MI , and PL . See the very similar BEGIN in the main glossary for 
additional information. 


UNTIL, ( addr 1 flag — ) 

Used to terminate a post-testing BEGIN, clause thus allowing for 
conditional looping of a program segment while "flag" is false. See 
BEGIN, above for more information. 


WHILE, ( addr 1 flag — addr 4 ) 

Used to begin a pre-testing BEGIN, clause thus allowing for 
conditional looping of a program segment while"flag" is true. See BEGIN, 
above for command format. 

REPEAT, ( addr 4 — ) 

Used to terminate a pre-testing BEGIN,..WHILE, clause. Additionally, 
REPEAT, resolves all forward addresses of the current WHILE, clause. 

See BEGIN, above. 


AGAIN, ( addr 1 — ) 

Used to terminate an unconditional BEGIN, clause. Execution cannot 
exit this loop unless a JMP, instruction is used. See BEGIN, clause for 
more information. 
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Parameter Passing 

NEXT ( ... addr ) 

Transfers control to the next FORTH word to be executed. The 
parameter stack is left unchanged. 

PUSH ( — addr ) 

Pushes a 16 bit value to the parameter stack whose low byte is 
found on the 6502 return stack and whose high byte is found in the 
accumulator. 

PUSHOA ( — addr ) 

Pushes a 16 bit value to the parameter stack whose low byte is 
found in the accumulator and whose high byte is zero. 


PUT ( — addr ) 

Replaces the value currently on top of the parameter stack with the 
16 bit value whose low byte is found on the 6502 stack and whose high 
byte is in the accumulator. 


PUTOA ( — addr ) 

Replaces the value currently on top of the parameter stack with the 
16 bit value whose low byte is in the accumulator and whose high byte 
is set to zero. 

BINARY ( — addr ) 

Drops the top value of the parameter stack and then performs a PUT 
operation described above. 

POP and POPTWO ( — addr ) 

POP drops one value from the parameter stack. POPTWO drops two 
values from the parameter stack. 


SETUP 


( — addr ) 


Moves one to four values to the N scratch area in the zero page and 
drops all values moved from the parameter stack. 

N ( — addr ) 

Points to a nine-byte scratch area in the zero page beginning at 
N-l and going to N+7. Typically used by words which use indirect-indexed 
addressing where addresses must be stored in the zero page. See SETUP 
above. 
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Opcodes ( 


ADC, 

AND, 

ASL, 

BIT, 

BRK, 

CLC, 

CLD, 

CLI, 

CLV, 

CMP, 

CPX, 

CPY, 

DEC, 

DEX, 

DEY, 

EOR, 

INC, 

INX, 

INV, 

JSR, 

JMP, 

LDA, 

LDX, 

LDY, 

LSR, 

NOP, 

ORA, 

PHA, 

PHP, 

PLA, 

PLP, 

ROL, 

ROR, 

RTI, 

RTS, 

SBC, 

SEC, 

SED, 

SEI, 

STA, 

STX, 

TAX, 

TAY, 

TSX, 

TXA, 

TXS, 

TYA, 



ATiases 


NXT, 


NEXT JMP, 

PSH, 

= 

PUSH JMP, 

PUT, 

r: 

PUT JMP, 

PSHA, 

= 

PUSHOA JMP 

PUTA, 

= 

PUTOA JMP, 

POP, 


POP JMP, 

POP2, 


POPTWO JMP 

XL, 


XSAVE LDX, 

XS, 


XSAVE STX, 

THEN, 

= 

ENDIF, 

END, 

= 

UNTIL, 





VII. valFORTH 1.1 SUPPLIED SOURCE LISTING 


Screen: 30 

0 ( Auto command ) 

1 

2 BASE 0 HEX 

3 

4 : ZAP < addr # — ) 

5 -DUP 

6 IF O+S 

7 DO D20A C0 7F AND I C! 

8 LOOP 

9 ELSE DROP 

10 ENDIF ; 

11 

12 : -WAIT ( — ) 

13 BEGIN 7TERMINAL NOT UNTIL ; 

14 

15 DCX ==> 


Screen: 31 

0 ( Auto command ) 

1 

2 : BEHEAD ( — ) 

3 0 >R CR ." Now protecting..." 

4 CR VOC-LINK 0 

5 BEGIN 

6 DUP 2- 0 

7 BEGIN 

8 DUP 1+ OVER R> 1+ >R 

9 R 15 MOD NOT IF ." ." ENDIF 

10 R 495 MOD NOT IF CR ENDIF 

11 C@ 63 AND WIDTH 0 MIN 1- 

12 ZAP PFA LFA 0 DUP NOT 

13 UNTIL 

14 DROP 0 DUP NOT 

15 UNTIL R> 2DR0P ; —> 


Screen: 32 


0 

1 

2 

( Auto command 


) 

: QUEST 

( 

— ) 

3 

CR 




4 

II 

m 

Save on disk: 

II 


5 

II 

■ 

press OPTION" 

CR 


6 

II 

■ 

Save or* cassettes 11 


7 

II 

m 

press SELECT" 

CR 


8 

II 

• 

Exit: 

II 


9 

II 

• 

press START" 

CR CR ; 


10 





11 

: DODISK 

( 

— ) 

12 

(SAVE) ’ SAVE 32 

+ 0EX 


13 

741 

0 128 - 1 1 

R/W ; 


14 





15 




==> 


Screen: 33 

0 ( Auto command 
1 


£ 

: QUEST2 

( - 

-n 

U 

." Format and save: 

4 

." press OPTION" 

CR 

5 

." Just save: 

It 

6 

." press SELECT" 

CR CR 

7 

WAIT 7TERMINAL - 

WAIT 

8 

." Prepare disk 

_ II 

9 

." press START" 


10 

WAIT -WAIT ; 


11 

: CSV 

< 

12 

." Prepare cassette " 

13 

." (piay/record) 

— " CR 

14 

." press START" 

CR 

15 

WAIT CSAVE -WAIT 

■ 


Screen: 34 

0 < Auto command 
1 

£ : DSV 

3 QUEST2 

4 4 = 

5 IF 

6 1 (FMT) 1 <> 

7 IF 

8 CR ." Format error" 

9 ELSE 

10 DODISK 

11 ENDIF 

12 ELSE 

13 DODISK 

14 ENDIF CR ; 

15 


Screen: 35 

0 ( Auto command 
1 

2 : DECIS < - 

3 BEGIN 

4 QUEST WAIT 7TERMINAL -WAIT 

5 DUP 1 = 

6 IF DROP 1 

7 ELSE 

8 2 = 

9 IF 

10 CSV 

11 ELSE 

12 DSV 

13 ENDIF 0 

14 ENDIF 

15 UNTIL ; 





BEEP ASCII 


Screen: 36 

0 ( Auto command ) 

1 

2 : AUTO ( — ) 

3 CCOMPILE] ’ CR 

4 ." Auto? Y/N " KEY 89 = CR 

5 IF 

6 CFA ’ ABORT 6 + ! 

7 » COLD CFA ’ ABORT 8 + ! 

8 -1 26 +ORIGIN ! 

9 ’ ZAP NFA DP ! 

10 BEHEAD DECIS ABORT 

11 ELSE 

12 DROP ." Auto aborted..." CR 

13 ENDIF ; BASE ! 

14 

15 


Screen: 39 

0 < Text output: 

1 

2 : BEEP 

3 0C0 0 

4 DO 

5 08 0D01F C! 

6 00 0D01F C! 

7 LOOP ; 

8 

9 : ASCII 

10 BL WORD 

11 HERE 1+ C@ 

12 STATE 0 

13 IF 


< 


6 0 DO LOOP 
6 0 DO LOOP 


( ccc, — 


14 COMPILE CLIT C, 

15 ENDIF ; IMMEDIATE 



<b>) 


—> 


Screen: 37 

0 
1 


Screen: 40 

0 < Text output: EJECT LISTS ) 
1 DCX 


4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


3 : EJECT 

4 12 EMIT ; 

5 

6 : LISTS 

7 0 <ROT 0+S 

8 DO 

9 CR I LIST 

10 1+ DUP 3 MOD 0= 

11 IF EJECT ENDIF 

12 ?EXIT 

13 LOOP 

14 DROP ; 

15 


( 


s # 


) 



==> 


Screen: 38 

0 < Text output: S: P: ) 

1 

2 BASE 0 HEX 

4 : S: ( f — ) 

5 PFLAG 0 SWAP 

6 IF 1 OR ELSE FE AND ENDIF 

7 PFLAG ! ; 

8 

9 : P: ( f — ) 

10 PFLAG 0 SWAP 

11 IF 2 OR ELSE FD AND ENDIF 

12 PFLAG ! ; 

13 

14 

15 ==> 


Screen: 41 

0 < Text output: PLISTS PLIST ) 

2 : PLISTS ( 5 # — ) 

3 PFLAG 0 <ROT 

4 ON P: 

5 LISTS 

6 CR PFLAG ! ; 

7 

8 : PLIST < 5 — ) 

9 1 PLISTS ; 

u IBID 

12 

13 

14 

15 


BASE ! 



Screen: 42 


Screen: 45 



0 

( Debug: B? [FREE! 

FREE ) 

0 

( 

Debug: CDUMP 


) 

1 

BOSE 0 DCX 


1 




2 

MS: )( 19 KLOAD ) 


2 

( 

Character dump routine 

) 

3 

HEX 


3 





4 



4 

• 

m 

CDUMP 

( a # 

— ) 

5 

: B? 

( — ) 

5 


PFLAG 0 (ROT OFF 

P: 


6 

BOSE 0 DUP ( 

Display ) 

6 


OVER + SWAP 



7 

DECIMAL . ( 

current ) 

7 


DO 



8 

BASE ! ; ( 

radix ) 

8 


CR I 5 U. R 



9 



9 


SPACE I DUP 10 

+ SWAP 


10 

: (FREE) 

( — r. ) 

10 


DO 



11 

2E5 0 PAD - ; 


11 


I C@ SPEMIT 



12 



12 


LOOP 



13 

: FREE 

( — ) 

13 


?EX IT 



14 

(FREE) U. ." bytes" 

CR ; 

14 


10 /LOOP 



15 


==> 

15 


CR PFLAG ! ; 


—> 


Screen: 43 



Screen: 46 


0 

1 

< 

Debug: H. CFALIT 

) 

0 

1 

( Stack print: DEPTH 

) 

X 

2 

II 

• 

CFALIT ( 

ccc, — (b> ) 

1 

2 

: DEPTH ( 

n — ) 

3 


STATE 0 



3 

S0 0 SP@ - 2/ 1- ; 


4 


[COMPILE! C 



4 



5 


[COMPILE! ’ CFA 



5 

CFALIT . VARIABLE X.S 


S 


SWAP IF [COMPILE! 

I 

END IF 

6 



7 


[COMPILE! LITERAL 

• 


7 

: XDOTS 

( — ) 

8 


IMMEDIATE 



8 

DEPTH 


9 





9 

IF 


10 


( H. —> ) ( ) 



10 

SP® 2- S0 0 2- 


11 

• 

* 

H. 


( b — ) 

11 

DO I 0 X.S 0 EXECUTE 


12 


BASE 0 HEX 

( 

Display ) 

12 

-2 +LOOP 


13 


SWAP 0 

( 

# in hex ) 

13 

ELSE 


14 


(####> TYPE 



14 

. " Stack empty 11 


15 


BASE ! ; 


—> 

15 

ENDIF ; 

==> 


Screen: 44 


0 

1 

( Debug: #DUMP 

) 

2 

3 

( memory dump ) 


4 

: #DUMP 

( a # — ) 

5 

O+S 


6 

DO 


7 

CR I 5 U. R I 


8 

DUP 8 + SWAP 


9 

DO 


10 

I C0 4 .R 


11 

LOOP 


12 

?EX IT 


13 

8 /LOOP 


14 

CR ; 


15 


==> 


Screen: 47 

0 < Stack print: .S U.S STOCK ) 
1 

2 : .S CFALIT . X.S ! XDOTS ; 

3 : U.S CFALIT U. X.S ! XDOTS 5 

4 


5 

: STKPRT 


6 

7 

CR . " ( 

" XDOTS 

8 

: STACK 


9 

IF 


10 

CFALIT 

STKPRT 

11 

ELSE 


12 

CFALIT 

NOOP 

13 

END IF 


14 

[ ’ PROMPT 11 + 

15 

LITERAL 

1 

1 


Screen s 48 

0 ( FORTH colon decompiler ) 

1 
£ 

3 0 VARIABLE .WORD 

4 

5 : PWORD 

6 £+ NFA ID. ; 

7 

8 : 1BYTE 

9 PWORD .WORD 0 C0 . 

10 1 .WORD +! ; 

11 

1£ : 1WORD 

13 PWORD .WORD 0 0 . 

14 2 .WORD + ! ; 

15 ==> 


Screen: 51 

0 ( FORTH colon decompiler ) 

1 

£ ELSE 

3 DUP CFALIT CLIT = 

4 IF 1BYTE 

5 ELSE 

6 DUP CFALIT COMPILE = 

7 IF PWORD CR NXT1 PWORD 

8 ELSE 

9 DUP 4-0 A9££ = 

10 IF STG 

11 ELSE PWORD ENDIF 

1£ ENDIF 

13 ENDIF 

14 ENDIF 

15 ENDIF ; —> 


Screen: 49 

0 ( FORTH colon decompiler ) 

1 : NP < r. — r. ) 

£ DUP CFALIT ;S = OVER 

3 CFALIT (;CODE> = OR 

4 IF PWORD CR CR PROMPT QUIT 

5 ENDIF 7TERMINAL 

6 IF DROP PROMPT QUIT ENDIF ; 

7 

8 : BRNCH 

9 PWORD ." to " .WORD 0 .WORD 0 

10 0 + U. £ .WORD +! ; 

11 

1£ : NXT1 

13 .WORD 0 U. £ SPACES 

14 .WORD 0 0 £ .WORD +! ; 

15 —> 


Screen: 50 

0 ( FORTH colon decompiler ) 

1 

£ : STG 

3 PWORD ££ EMIT .WORD 0 
DUP COUNT TYPE ££ EMIT 

5 C0 .WORD 0+1+ .WORD ! ; 

6 

7 : CKIT 

8 DUP CFALIT ©BRANCH = 

9 OVER CFALIT BRANCH = OR 

10 OVER CFALIT (LOOP) = OR 

11 OVER CFALIT (+LOOP) = OR 

1£ OVER CFALIT (/LOOP) = OR 

1£ 

13 IF BRNCH 

14 ELSE DUP CFALIT LIT = 

15 IF 1WORD ==> 


Screen: 5£ 

0 ( FORTH colon decompiler ) 

1 

£ : 7DOCOL 

3 DUP £- 0 

4 C ’ : 1£ + 3 LITERAL - 

IF ." Primitive pfa dump:" 

8 £- 0 18 #DUMP 

7 PROMPT QUIT 

8 ENDIF ; 

9 
10 
11 
1£ 

13 

14 

15 ==> 


Screen: 53 

0 ( FORTH colon decompiler ) 

1 

£ : DCMPR ( 

3 DUP NFA CR CR DUP ID. 

4 C0 40 AND 

5 IF ." (IMMEDIATE)" 

6 ENDIF 

7 CR CR 7DOCOL .WORD ! 

8 BEGIN NXT1 NP CKIT CR 

9 

10 : DECOMP 

11 [COMPILE] ’ DCMPR ; 

1£ 

13 

14 

15 BASE ! ;S 


PFA — ) 


AGAIN ; 






) 


Screen: 54 

0 
1 
£ 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 57 

0 ( fig editor: MARK 
1 

£ : MARK 

3 10 0 

4 DO 

5 I LINE UPDATE 

6 DROP 

7 LOOP ; 

8 
9 

10 
11 
1£ 

13 

14 

15 — > 


Screen: 55 Screen: 58 


0 

0 

( 

fig editor: WHERE 

1 

1 



£ 

£ 

VOCABULARY EDITOR IMMEDIATE 

3 

3 



4 

4 

( 

Note: the fig bug is fixed ) 

5 

5 

( 

in WHERE below. ) 

6 

6 



7 

7 

• 

• 

WHERE ( n n — 

8 

8 


£DUP DUP B/SCR / DUP SCR ! 

9 

9 


. " Scr # " DECIMAL . SWAP 

10 

10 


C/L /MOD C/L * ROT BLOCK + 

11 

11 


CR C/L -TRAILING TYPE 

1£ 

1£ 


CR HERE Cl? - £- 0 MAX SPACES 

13 

13 


1 £FE C! 1C EMIT 0 £FE C! 

14 

14 


[COMPILED EDITOR QUIT ; 

15 

15 


; 


Screen: 56 

0 < fig editor: TEXT LINE ) 

1 

£ BASE @ HEX 


3 

4 

5 

6 

7 

8 
9 

10 

11 

1£ 

13 

14 

15 


< This editor is based on the ) 
( example editor supplied in ) 
( the "fig-FORTH Installation ) 
( Manual." ) 


: TEXT 

HERE C/L 1+ BLANKS WORD 
HERE PAD C/L 1+ CMOVE ; 


LINE 

DUP FFF0 AND 17 7ERR0R 
SCR @ (LINE) DROP : 




Screen: 59 

0 ( fig editor: #L’s -MOVE ) 

1 

£ EDITOR DEFINITIONS 

3 

4 : #LOCATE ( — n n ) 

5 R# & C/L /MOD ; 

6 

7 : #LEAD ( — n n ) 

8 #LQCATE LINE SWAP ; 

9 

10 : #LAG ( — n n ) 

11 #LEAD DUP > R + C/L R> - ; 

1£ 

13 : —MOVE ( n n — ) 

14 LINE C/L CMOVE UPDATE ; 

15 —> 




s 


) 


I TOP 


Screen: 60 

0 ( fig editor: H E 
1 

£ : H ( n 

3 LINE PAD 1+ C/L 

4 DUP POD C! CMOVE ; 

5 

6 : E < n 

7 LINE C/L BLANKS UPDATE ; 

8 

9 : S ( n 

10 DUP 1- 0E 

11 DO 

12 I LINE 

13 I 1+ -MOVE 

14 -1 +LOOP 

15 E ; 


— ) 


— ) 


— ) 


==> 


Screen: 63 

0 ( fig editor: 
1 

£ : I 

3 DUP S R ; 

4 


5 : TOP 

6 0 R# ! ; 

7 

a 

9 

10 

li 

i£ 

13 

14 

15 



< — ) 


— > 


Screen: 61 

0 < fig editor: D M ) 

1 

£ : D ( n — ) 

3 DUP H 0F DUP ROT 

4 DO 

5 I 1+ LINE 

6 I -MOVE 

7 LOOP 
S E ; 

9 

10 : M ( n — ) 

11 R# +! CR SPACE 

12 #LEAD TYPE 14 EMIT #LAG 

13 TYPE #LOCATE . DROP ; 

14 

15 —> 


Screen: 64 

0 ( fig editor: CLEAR 
1 

£ : CLEAR 

3 SCR ! 10 0 

4 DO 

5 FORTH I EDITOR E 

6 LOOP ; 

7 

8 : COPY 

9 B/SCR * OFFSET 0 + SWAP 

10 B/SCR * B/SCR OVER + SWAP 

11 DO 

12 DUP FORTH I BLOCK 

13 2- ! 1+ UPDATE 

14 LOOP 

15 DROP : ==> 


COPY ) 



( n n — ) 


Screen: 62 


0 

( 

fig 

editor: T L R 

P 


> 

1 







2 

ft 

» 

T 


< 

tt 

— > 



DUP 

C/L * R# ! 




4 


DUP 

H 0 M 5 




5 







6 

m 

L 



< 

— > 

7 


SCR 

0 LIST 0 M ; 




a 







9 

ft 

« 

R 


< 

tt 

— ) 

10 


PAD 

1+ SWAP -MOVE ; 




li 







12 


P 


< 

n 

— > 

13 


1 TEXT R : 




14 







15 






==> 


Screen: 65 

0 ( fig editor: 1LINE FIND ) 

1 

£ : 1LINE < — f ) 

3 #LAG PAD COUNT 

4 MATCH R# +! ; 

6 : FIND < — ) 

7 BEGIN 

8 3FF R# 0 < 

9 IF 

10 TOP PAD HERE C/L 

11 1+ CMOVE 0 ERROR 

12 ENDIF 

13 1LINE 

14 UNTIL ; 

15 —> 




Screen: 66 

0 ( fig editor: DELETE ) 

1 

2 : DELETE ( n — ) 

3 > R #LAG + FORTH R - 

4 #LAG R MINUS R# +! #LEAD 

5 + SWAP CMOVE R> BLANKS 

6 UPDATE ; 

7 

8 
9 

10 

11 

12 

13 

14 


15 ==> 


Screen: 67 

0 ( fig editor: N F B X ) 

1 

2 : N ( — ) 

3 FIND 0 M ; 

4 

5 : F ( — ) 

6 1 TEXT N ; 

7 

8 : B ( — ) 

9 PAD C@ MINUS M ; 

10 

11 : X ( — ) 

12 1 TEXT FIND 

13 PAD C@ DELETE 

14 0 M ; 

15 —> 


Screen: 69 

0 ( End of fig-FORTH editor ) 

1 

2 FORTH DEFINITIONS DCX 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 BASE ! 


Screen: 70 

0 
1 
2 

3 

4 

5 

6 
7 

a 

9 

10 

11 

12 

13 

14 

15 


Screen: 68 

0 ( fig editor: TILL C ) 

1 

2 : TILL ( — ) 

3 #LEAD + 1 TEXT 

4 1LINE 0= 0 7ERR0R 

5 #LEAD + SWAP - 

6 DELETE 0 M ; 

7 

8 : C 

9 1 TEXT PAD COUNT #LAG ROT 

10 OVER MIN > R FORTH R R# +! 

11 R - >R DUP HERE R CMOVE 

12 HERE #LEAD + R> CMOVE R> 

13 CMOVE UPDATE 0 M ; 

14 

15 ==> 


Screen: 71 

0 
1 
2 

3 

4 

5 

6 

7 

8 
9 

10 
11 
12 

13 

14 

15 


) 


Screen: 72 

0 ( Disk copy routines 

1 BASE 0 DCX 

2 

3 0 VARIABLE SEC/PAS 

4 0 VARIABLE SECNT 

5 

6 : AXLN ( system ) 

7 4 PICK 0 

8 DO 3 PICK I 128 * + 

9 3 PICK I + 3 PICK R/W 

10 LOOP 2DR0P 2DR0P ; 

11 

12 : DCSTP 

13 741 @ PAD DUP 1 AND - 

14 0 128 U/ SWAP DROP 

15 SEC/PAS ! 0 SECNT i ; ==> 


Screen: 73 

0 ( Disk copy routines ) 

1 

2 : DISKCOPY1 « — ) 

3 DCSTP 

4 BESIN 

5 CR CR ." Insert source and pu 

6 sh START" WAIT 

720 SECNT 0 - SEC/PAS 0 MIN 

8 DUP > R PAD DUP 1 AND - SECNT 

9 0 2DUP 5 PICK <ROT 1 AXLN 

10 CR CR ." Insert dest. and pu 

11 sh START” WAIT 0 AXLN CR 

12 R> SECNT +! SECNT 0 DUP . 

13 ." sectors copied" 720 = 

14 UNTIL EMPTY-BUFFERS 

15 CR ." Done" CR ; —> 


Screen: 75 

0 
1 
2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


Screen: 76 

0 ( 6502 Assembler in FORTH ) 

1 < 

2 ( Originally written by 

3 ( Patrick Mu1larky. 

4 ( 

5 ( Modified extensively 2/82 

6 ( by Stephen Maguire, 

7 ( Valpar International 

8 ( 

9 ( 

10 ( This assembler conforms to the 

11 ( fig "INSTALLATION GUIDE" and 

12 ( to APX versions of FORTH. 

13 < 

14 ( ) 

15 ==> 


Screen: 74 

0 < Disk copy routines ) 

1 

2 : DISKC0PY2 ( — ) 

3 DCSTP 

4 CR ." Insert source in drive 1 

5 " CR ." Insert dest. in drive 2 

6 " CR ." Press START to copy" 

7 WAIT 

8 BEGIN 


Screen: 77 

0 ( 6502 Assembler in FORTH 

1 < 

2 ( Now supports: 

3 ( 

4 ( IF, . . .ELSE, . . .ENDIF, 

5 ( BEGIN,... WHILE,... REPEAT, 

6 ( BEGIN, .. .AGAIN, 

7 ( BEGIN,...any flag UNTIL, 

8 ( C; & END-CODE 


9 

720 SECNT 0 - SEC/PAS 0 MIN 

9 

< 

;CODE 

10 

DUP > R PAD DUP 1 AND - SECNT 

10 

< 


11 

0 2DUP 5 PICK <ROT 

11 

( 

Also supports: 

12 

1 AXLN 720 + 0 AXLN 

12 

< 


13 

R> SECNT +! SECNT 0 720 = 

13 

( 

compiler security 

14 

UNTIL EMPTY-BUFFERS 

14 

< 

definition checking 

15 

CR ." Done" CR ; BASE ! 

15 




--> 



Screen: 7Q 

0 ( 6502 Assembler in FORTH ) 

1 ’( TRANSIENT TRANSIENT )( ) 

2 BASE @ HEX 

3 ASSEMBLER DEFINITIONS 

4 

5 : SB 


6 

7 

<BUILDS C, 

DOES) @ C, 

• 

» 

f 

8 

000 

SB 

BRK, 

018 

SB 

CLC, 

9 

0D8 

SB 

CLD, 

058 

SB 

CLI, 

10 

0B8 

SB 

CLV, 

0CA 

SB 

DEX, 

11 

088 

SB 

DEY, 

0E8 

SB 

INX, 

12 

0C8 

SB 

INY, 

0EA 

SB 

NOP, 

13 

048 

SB 

PHA, 

008 

SB 

PHP, 

14 

068 

SB 

PLA, 

028 

SB 

PLP, 

15 

040 

SB 

RTI, 

060 

SB 

RTS, 


Screen: 79 

0 ( 6502 Assembler in 

FORTH 

1 

038 

SB 

SEC, 

0F8 

SB 

SED, 

d 

078 

SB 

SEI, 

0AA 

SB 

TAX, 

3 

0BA 

SB 

TSX, 

08A 

SB 

TXA, 

4 

09A 

SB 

TXS, 

098 

SB 

TYA, 

5 

6 

0A8 

SB 

TAY, 





7 0 VARIABLE >J s ) 1 )J * ; 

8 

9 : 3BY 

10 <BUILDS C, DOES) C® DUP 4C = 

11 IF >J @ IF DROP SC ENDIF 

12 ENDIF C, , 0 )J ! ; 

13 

14 04C 3BY JMP, 06C 3BY JMPO, 

15 020 3BY JSR, 06C 3BY )JMP, —> 


Screen: 80 

0 ( 6502 Assembler in FORTH ) 

1 

2 : 256< DUP 100 ( HEX ) U< ; 


4 

70 

CONSTANT 

VC 

( 

over clear ) 

5 

50 

CONSTANT 

VS 

( 

over set ) 

6 

B0 

CONSTANT 

CC 

( 

carry c1ear ) 

7 

90 

CONSTANT 

CS 

( 

carry set ) 

8 

D0 

CONSTANT 

EQ 

< 

zero ) 

9 

F0 

CONSTANT 

NE 

( 

non-zero ) 

10 

30 

CONSTANT 

PL 

( 

positive ) 

11 

12 

13 

: 

1 ?PAIRS 

IF, 

4C 

c, 

, ; IMMEDIATE 

14 

15 

( 

:, 0 C, HERE 

2 ; 

IMMEDIATE 

==> 


Screen: 81 

0 ( 6502 Assembler in FORTH ) 

1 

2 : ENDIF, 

3 DUP 2 = IF 

4 DROP DUP HERE SWAP - 

5 DUP 7F > 5 7ERROR 

6 DUP -80 < 5 ?ERROR 

7 SWAP 1- C! 

8 ELSE 

3 3 ?PAIRS HERE SWAP ! 

10 ENDIF ; IMMEDIATE 

11 

12 : ELSE, 

13 DUP 2 ?PAIRS 4C C, HERE 0 , 

14 <ROT [COMPILE] ENDIF, 3 ; 

15 — > 


Screen: 82 


0 

1 

2 

( 

6502 Assembler in 

FORTH 

0 

0 

THEN, 


3 

4 


[COMPILE] ENDIF, ; 

IMMEDIATE 

5 

* 

BEGIN, 


6 

7 


HERE 1 ; 

IMMEDIATE 

8 

9 

10 

• 

0 

UNTIL, 

SWAP 1 7PAIRS C, 
HERE 1+ - DUP -80 


11 
12 


< 5 7ERROR C, ; 

IMMEDIATE 

13 

0 

0 

END, 


14 

15 


[COMPILE] UNTIL, ; 

IMMEDIATE 


Screef 

83 

0 ( 
i 

6502 Assembler in FORTH 

1 

£ s 

WHILE, 


SWAP 1 7PAIRS [COMPILE] IF, 

4 

DROP 4 ; IMMEDIATE 

vJ 

6 : 

REPEAT, 

7 

4 7PAIRS SWAP 4C C, , 2 

8 

[COMPILE] ENDIF, ; IMMEDIATE 

9 

11 10 

CONSTANT MI ( negative ) 

12 

13 : 

END-CODE 

14 

[COMPILE] C; ; IMMEDIATE 

15 

__' 


Screen: 84 

0 ( 6502 Assembler in FORTH ) 

1 0D VARIABLE MODE < ABS mode ) 

£ 00 VARIABLE ACC ( A-reg? > 

3 

4 : BIT, 

5 256< IF 24 C, C, 

6 ELSE 2C C, , ENDIF ; 

7 

8 : CKMODE 

9 mode @ = 

10 IF ( MODE = MODE - 8 ) 

11 256< ( if addr < 256 ) 

12 IF 

13 -08 MODE +! 

14 ENDIF 

15 ENDIF ; ==> 


Screen: 87 

0 ( 6502 Assembler in FORTH ) 

1 

2 : OPCODE 

3 03 ZPAGE MODE <3 ID = 

4 MODE <3 19 = OR 

5 IF 10 OR ENDIF ; 

6 

7 : ME 

8 <BUILDS C, 

9 DOES) OPCODE MODE @ 9 = 

10 IF 4 - ENDIF !ADDR ; 

11 

12 : M3 

13 <BUILDS C, 

14 DOES) OPCODE !ADDR ; 

15 —) 


Screen: 85 

0 ( 6502 Assembler in FORTH ) 

1 


2 

: M0 





3 

<BUILDS 




4 


c, 




5 

DOES) 




6 


SWAP 0D 

CKMODE 



7 


ID CKMODE SWAP 



8 


C@ MODE 

@ OR C, 



9 


£56< IF 

C, ELSE 

9 

ENDIF 

10 


0D MODE 

! ; < 

ABS mode 

11 






1 £~ 

00 

M0 ORA, 

£0 

M0 

AND, 

13 

40 

M0 EOR, 

60 

M0 

ADC, 

14 

80 

M0 STA, 

A0 

M0 

LDA, 

15 

C0 

M0 CMP, 

E0 

M0 

SBC, - 


Screen: 88 

0 ( 6502 Assembler in FORTH ) 


1 


0AC 

M2 

LDY, 

0AE 

M2 LDX, 

2 


0CC 

M2 

CPY, 

0EC 

M2 CPX, 

3 

4 


08C 

M3 

STY, 

08E 

M3 STX, 

5 

m 

m 

X) 

01 

MODE 

! ; ( 

Caddr,XI ) 

6 

m 

m 

# 

09 

MODE 

! ; < 

immediate 

7 

m 

m 

) Y 

11 

MODE 

! ; ( 

Caddr],Y 

8 

m 

m 

,x 

ID 

MODE 

! ; < 

addr,X ) 

9 

m 

,Y 

19 

MODE 

! ; ( 

addr,Y ) 

10 

11 

m 

.A 

01 

ACC 

! ; ( 

a - reg ) 

12 

0A 

i SB 

ASL 


£A SB 

ROL. A, 

13 

14 

4A 

1 SB 

LSR. A, 

6A SB 

ROR. A, 


15 ==) 


Screen: 86 

0 < 6502 Assembler in FORTH ) 

1 : !ADDR C, £56< IF C, ELSE , 

2 ENDIF 0D MODE ! ; 

4 : ZPAGE 

5 OVER 100 U< IF F7 AND ENDIF ; 

6 

7 : Ml 

8 <BUILDS C, DOES) CC» ACC @ 


9 

IF 

FB 

AND C, 

ELSE 

MODE (3 ID - 
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Screen: 14£ 

0 ( ValFORTH Video editor VI.0 ) 
1 

£ : CBLANK ( - ) 

3 CURLOC DUP C0 1£7 

4 AND SWAP C! ; 

5 

6 : UPCUR ( — > 

7 CBLANK YLOC 0 1- DUP 

8 0< IF DROP 15 ENDIF 

9 YLOC ! CSHOW ; 

10 

11 : DNCUR < — ) 

1£ CBLANK YLOC 0 

13 1 + DUP 15 > 

14 IF DROP 0 ENDIF 

15 YLOC ! CSHOW ; ==> 


Screen: 140 

0 < ValFORTH Video editor VI. 0 ) 
1 

£ BASE 0 DCX ’ ( > SCD ) ( 68 KLOAD ) 
3 


4 VOCABULARY EDITOR IMMEDIATE 

5 EDITOR DEFINITIONS 

6 


7 

0 

VARIABLE 

XLOC 

( 

X coord. 

) 

8 

0 

VARIABLE 

YLOC 

( 

Y coord. 

) 

9 

0 

VARIABLE 

LSTCHR 

( 

last key 

) 

10 

0 

VARIABLE 

?ESC 

< 

coded char?) 

11 

0 

VARIABLE 

TBLK 

< 

top block 

) 

1£ 

0 

VARIABLE 

UPSTAT 

o 

I— 

ALLOT < map) 

1 Lj 

14 

1 

5 CONSTANT 15 

32 

CONSTANT 

3£ 

15 

1£8 CONSTANT 1£8 



==> 
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0 < ValFORTH Video editor VI.0 ) 
1 

£ : LFCUR 

3 CBLANK XLOC 0 

4 1 - DUP 0 < 

5 IF DROP 31 ENDIF 

6 XLOC ! CSHOW ; 

7 

8 : RTCUR 

9 CBLANK XLOC 0 

10 1+ DUP 31 > 

11 IF DROP 0 ENDIF 

1£ XLOC ! CSHOW ; 

13 

14 : EDMRK 

15 1 YLOC 0 4 / UPSTAT + C! ; — > 


< — ) 

( AT L-SIDE?) 
( FIX IF SO ) 


( — ) 

( AT R-SIDE?) 
( FIX IF SO ) 
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0 < ValFORTH Video editor VI.0 ) 
1 

£ : LNINS ( — ) 

3 CBLANK 

4 4 YLOC 04/ 

5 DO 1 I UPSTAT + C! LOOP 

6 YLOC 0 15 < 

7 IF 

8 BOL DUP 32 + 

9 15 YLOC 0 - 32 * 

10 <CMOVE 

11 ENDIF 

12 BOL 32 ERASE 

13 CSHOW EDMRK ; 

14 

15 ==> 
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0 < ValFORTH Video editor VI.0 ) 
1 

2 : SCRSV ( — ) 

3 88 0 32 + PAD 512 BSCD> 

4 4 0 

5 DO 

6 I UPSTAT + C@ 

7 0 I UPSTAT + C! 

8 IF 

9 PAD 128 I * + 

10 TBLK 0 I + BLOCK 

11 128 CMOVE UPDATE 

12 ENDIF 

13 LOOP 

14 0 XLOC ! 0 YLOC ! ; 

15 —> 
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0 ( ValFORTH Video editor VI.0 ) 
1 


2 

: LNDEL 

< — 

) 

3 

CBLANK 



4 

4 YLOC 0 4 / 



5 

DO 1 I UPSTAT + C! LOOP 



6 

YLOC 0 15 < 



7 

IF BOL < 

FROM 

) 

8 

DUP 32 + SWAP ( 

TO 

) 

9 

15 YLOC 0 - 32 * ( 

# CH 

) 

10 

CMOVE 



11 

END IF 



12 

BOL 15 YLOC 0 - 



13 

32 * + 32 ERASE 



14 

CSHOW EDMRK ; 



15 


— 

•> 
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0 ( ValFORTH Video editor VI.0 ) 
1 

2 : SCRGT ( -- ) 

3 4 0 

4 DO 

5 TBLK 0 

6 I + BLOCK 

7 PAD 128 I * + 

8 128 CMOVE 

9 LOOP 

10 PAD 88 0 32 + 

11 512 > BSCD ; 

12 

13 

14 

15 ==> 
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0 ( ValFORTH Video editor VI. 0 ) 
1 

£ : RUB ( — ) 

3 XLOC 0 0= NOT ( ON L-EDGE? ) 

4 IF LFCUR 0 CURLOC C! 

5 CSHOW EDMRK 

6 ENDIF ; 

7 

8 : PTCHR ( — ) 

9 EDMRK 

10 LSTCHR 0 127 AND 

11 DUP LSTCHR ! 

12 > SCD CURLOC C! 

13 RTCUR XLOC 0 0= 

14 IF DNCUR ENDIF 

15 0 ?ESC ! CSHOW ; ==> 
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0 ( ValFORTH Video editor VI.0 ) 
1 

2 : NWSCR ( -1/0/1 — ) 

3 CBLANK DUP 

4 IF SCRSV ENDIF 2* 2* 

5 TBLK 0+0 MAX TBLK ! SCRGT 

6 TBLK 0 8 /MOD 

7 DUP <ROT SCR ! 

8 IF 44 ELSE 53 ENDIF 

9 ?IK NOT 

10 IF 

11 44 = SWAP 2* + DUP SCR ! 0 

12 ENDIF 

13 88 0 17 + C! 

14 0 84 C! 11 85 ! 1 752 C! 

15 .2 SPACES CSHOW ; —> 



VI.® ) 


VI.® ) 
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® ( ValFORTH Video editor 
1 

£ : SPLCHR 1 ?ESC ! ; < — ) 

J/ 

4 : EXIT ( — ) 

5 CBLANK 19 LSTCHR ! 

6 ® XLOC ! ® YLOC ! ; 

7 

6 : EDTABT ( — ) 

9 UPSTAT 4 ® FILL 

10 EXIT ; 

11 
IS 

13 

14 

15 ==> 
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0 ( ValFORTH Video editor 
1 

2 s (V) ( TBLK — ) 

3 DECIMAL 

4 DUP BLOCK DROP TBLK ! 

5 UPSTAT 4 0 FILL 

6 1 PFLAG ! 0 GR. 

7 1 752 C! CLS 

8 1 559 C@ £52 

9 AND OR 559 C! 

10 112 560 @ 6 + C! 

11 112 560 @ 23 + C! 

12 ." Screen #" 11 SPACES 

13 ." ValFORTH" 

14 ® NWSCR 

15 —> 
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0 < ValFORTH Video editor VI.0 ) 
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Screen: 154 

0 ( ValFORTH Video editor 
1 


2 : 

CONTROL 




( n — ) 

2 


3 

DUP 

19 

= 

IF 

DROP 

EXIT 

ELSE 


< Main loop of editor 

4 

DUP 

17 

= 

IF 

DROP 

EDTABT 

ELSE 

4 


5 

DUP 

28 

= 

IF 

DROP 

UPCUR 

ELSE 

5 

BEGIN 

6 

DUP 

£9 

= 

IF 

DROP 

DNCUR 

ELSE 

6 

KEY DUP LSTCHR ! 

7 

DUP 

30 

ss 

IF 

DROP 

LFCUR 

ELSE 

7 

?ESC e 

8 

DUP 

31 

as 

IF 

DROP 

RTCUR 

ELSE 

8 

IF 

9 

DUP 

126 

ss 

IF 

DROP 

RUB 

ELSE 

9 

PTCHR 0 LSTCHR 

10 

DUP 

157 

SS 

IF 

DROP 

LNINS 

ELSE 

10 

ELSE 

11 

DUP 

156 

SS 

IF 

DROP 

LNDEL 

ELSE 

11 

CONTROL 

12 


27 

= 

IF 

DROP 

SPLCHR 

ELSE 

12 


13 








13 

LSTCHR @ 19 = 

14 








14 

UNTIL 

15 







—> 

15 



VI.0 ) 
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0 < ValFORTH Video editor VI. 0 ) 
1 

£ PTCHR < IF NOTHING SPECIAL ) 

3 ENDIF ENDIF ENDIF ENDIF 

4 ENDIF ENDIF ENDIF ENDIF 

5 ENDIF ENDIF ; 

6 
7 
0 
9 

1® 

11 

12 

13 

14 

15 ==> 
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0 < ValFORTH Video editor VI. 0 ) 
1 

CBLANK SCRSV ® 767 C! 

3 £ 560 @ 6 + Ci 

2 560 @ £3 + C! 

5 £ 559 C@ £52 

6 AND OR 559 C! 

7 0 752 C! CLS CR 

8 ." Last edit on screen # " 

9 SCR & . CR CR ; 

10 

11 FORTH DEFINITIONS 

12 


13 

14 

15 


V 

1 MAX B/SCR * 
EDITOR (V) : 


s — ) 


— > 
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@ ( ValFORTH Video editor 
1 

2 : L 

3 SCR e DUP 1+ 

B/SCR * SWOP B/SCR * 
EDITOR TBLK 0 DUP <ROT 
<= <ROT > AND 
IF 

EDITOR TBLK @ 

ELSE 

SCR @ B/SCR * 

END IF 

EDITOR (V) : 


4 

5 

6 

7 

8 
9 

10 
11 
1 £ 

13 

14 

15 


VI.0 ) 
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Screen: 157 

0 < ValFORTH Video editor 
1 

2 : CLEAR 

B/SCR * B/SCR O+S 
DO 

FORTH I BLOCK 
B/BUF BLANKS UPDATE 
LOOP : 


3 

4 

5 

6 

7 

8 
9 

10 
11 
12 

13 

14 

15 


VI.0 ) 


( s — ) 


COPY ( si s2 — ) 

B/SCR * OFFSET C- + 

SWAP B/SCR * B/SCR O+S 
DO DUP FORTH I 
BLOCK 2- ! 

1+ UPDATE 

LOOP DROP : —> 
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Screen: 158 

0 ( ValFORTH Video editor 
1 


VI.0 ) 
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3 
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Not e: 


the fig bug is fixed ) 
in WHERE below. ) 


HEX 

: WHERE 


( [ n n ] — 
2DUP DUP B/SCR / DUP SCR ! 

." Scr # " DECIMAL . SWAP 
C/L /MOD C/L * ROT BLOCK + 

CR C/L -TRAILING TYPE 
CR HERE C@ -2-0 MAX SPACES 
1 2FE C! 1C EMIT 0 2FE C! 
CCOMPILED EDITOR QUIT ; 

BASE ! 
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Screen: 1£2 

0 < DOS: input/output routines ) 
1 

2 BOSE 0 HEX 

3 

4 340 VARIABLE IOCB 

5 0 VARIABLE 10.X 

6 0 VARIABLE 10.CH 

7 

8 : IOCC 

9 10 * 70 MIN DUP 10. X C! 

10 340 + IOCB ! ; 

11 

12 : <I0> 

13 <BUILDS , 

14 DOES) 0 IOCB 0 + ; 

15 ==> 
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0 ( DOS: system words > 

1 


£ 

1— 

<I0> 

ICCOM 

3 

<I0> 

ICSTA 

•n 

v?; 

4 

<I0> 

ICBAL 

8 

<IQ> 

ICBLL 

4 

A 

<I0> 

ICAX1 

B 

<I0> 

ICAX2 

5 

C 

<I0> 

ICAX3 

D 

<I0> 

ICAX4 

6 

E 

<I0> 

ICAX5 

p 

<I0> 

ICAX6 


7 

8 

9 CODE XCIO 

10 XSAVE STX, 10.X LDX, 

11 10.CH LDA, E456 JSR, 

12 XSAVE LDX, 10.CH STO, 

13 TVA, PUSH0O JMP, 

14 C; 

15 —> 
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0 ( DOS: OPEN CLOSE PUTC BETC ) 

1 

2 : OPEN < adr nl n2 n3 — n4 ) 

3 IOCC ICAX2 C! ICAX1 C! 

4 ICBAL ! 03 ICCOM C! XCIO ; 

CT 

wJ 

6 : CLOSE ( nl — ) 

7 IOCC 0C ICCOM C! XCIO DROP ; 

8 

9 : PUT ( c nl — n2 ) 

10 IOCC 10.CH C! ©B 

11 ICCOM C! XCIO ; 

12 

13 : BET < nl — c n2 ) 

14 IOCC 7 ICCOM C! XCIO 

15 10.CH C0 SWAP 5 ==> 


Screen: 165 

0 ( DOS: BET/PUTREC STATUS DEV ) 
1 

2 : BETREC ( adr nl n2 — n3 ) 

3 IOCC 5 ICCOM C! ICBLL ! 

4 ICBAL ! XCIO ; 

6 : PUTREC ( adr nl n£ — n3 ) 

7 IOCC 9 ICCOM C! ICBLL ! 

8 ICBAL ! XCIO ; 

9 

10 : STATUS ( nl — r.2 ) 

11 IOCC ICSTA C0 ; 

12 

13 : DEVSTAT ( nl — n2 n3 n4 ) 

14 IOCC 0D ICCOM Ci XCIO 

15 > R 2EA 0 2EC 0 R> ; —> 
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0 ( DOS: SPECIAL ) 

1 

£ : SPECIAL 

3 ( nl n2 n3 n4 n5 n6 n7 n8 — n9) 
IOCC ICCOM C! ICAX6 C! 

ICAX5 C! ICAX4 Ci ICAX3 C! 

6 ICAX2 C! ICAX1 Ci XCIO ; 

7 

8 
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15 BASE ! 
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0 

( Otari 850 

download 


) 

0 

CONTENTS OF THIS DISK 

, cont 

: 

1 






l 




2 

BOSE @ HEX 





2 

fig EDITOR: 

56 

LOAD 







Lj 

BUFFER RELOCATION: 

94 

LOAD 

4 

CODE DO-SIO 





4 

AUTO-BOOT UTILITY: 

30 

LOAD 

5 

XSAVE STX, 

0 # LDA, 



5 

OPERATING SYS. WORDS: 

162 

LOAD 

6 

E459 JSR, 





6 

850 DOWNLOAD (RS-232) 

: 168 

LOAD 

7 

XSAVE LDX, 

NEXT 

JMP, 



7 

(OPSYS AND 850 NEED 

ASSEMBLER) 

8 






8 




9 

: SET-DCB 





9 




10 

50 300 Ci 

1 

301 

C! 


10 




11 

3F 302 Ci 

40 

303 

C! 


11 




12 

500 304 ! 

5 

306 

C! 


12 




13 

0 307 C! 

C 

308 

C! 


13 




14 

0 309 ! 

0 

30B 

Ci ; 


14 




15 





==> 
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Screen: 17£ 


0 

< Atari 850 download 


) 

0 

1 




1 

d 

CODE RELOCATE 



d 

3 

XSAVE STX, 506 JSR, 



3 

4 

HERE 8 + JSR, XSAVE LDX, 

» 

4 

5 

NEXT JMP, 0C )JMP, 



5 

6 




6 

7 




7 

8 

: RS232 


( — ) 

8 

9 

HERE 2E7 ! SET-DCB 

DO-SIO 

9 

10 

500 300 0C CMOVE DO 

-SIO 


10 

11 

RELOCATE 2E7 @ HERE 

- ALLOT 

11 

12 

HERE FENCE ! ; 



12 

13 




13 

14 




14 

15 
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1 

15 
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CONTENTS OF THIS DISK 
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£ 

PRINTER UTILITIES: 

38 

LOAD 

iZL 

3 

DEBUGGING AIDS: 

42 

LOAD 


4 

VALFORTH EDITOR 1.0: 

140 

LOAD 

4 

5 

ASSEMBLER: 

76 

LOAD 

5 

6 

COLOR COMMANDS: 

100 

LOAD 

6 

7 

GRAPHICS: 

104 

LOAD 

7 

8 

GRAPHICS DEMO: 

112 

LOAD 

8 

9 

SOUNDS: 

114 

LOAD 

9 

10 

FLOATING POINT: 

120 

LOAD 

10 

11 

<FP REQUIRES ASSEMBLER FIRST) 

11 

1 d 

SCREEN CODE CONVERS.: 

136 

LOAD 

12 

13 

FORMATTER: 

92 

LOAD 

13 

14 

DISK COPIERS: 

72 

LOAD 

14 

15 

(continued on next 

screen) 
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0 Disk Error! 
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Screen: 178 

0 ( Error messages 

2 Use only in Definitions 

4 Execution only 

6 Conditiona1s not paired 

7 

8 Definition not finished 

9 

10 In protected dictionary 

11 

12 Use only when loading 

13 

14 Off current screen 

15 
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0 ( Error messages 
1 

£ Stack empty 
4 Dictionary full 
6 Wrong addressing mode 

8 Is not unique 

9 

10 Value error 

11 

12 Disk address error 

13 

14 Stack full 

15 
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